{% endif %}
diff --git a/doc/_themes/saltstack2/static/images/DOCBANNER.jpg b/doc/_themes/saltstack2/static/images/DOCBANNER.jpg
index f68f0787bb..81e276efdd 100644
Binary files a/doc/_themes/saltstack2/static/images/DOCBANNER.jpg and b/doc/_themes/saltstack2/static/images/DOCBANNER.jpg differ
diff --git a/doc/_themes/saltstack2/static/images/SaltStack_white.svg b/doc/_themes/saltstack2/static/images/SaltStack_white.svg
new file mode 100644
index 0000000000..046c1156f7
--- /dev/null
+++ b/doc/_themes/saltstack2/static/images/SaltStack_white.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/doc/conf.py b/doc/conf.py
index fb4b5dd319..1b5c258fe2 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -106,6 +106,7 @@ MOCK_MODULES = [
'tornado',
'tornado.concurrent',
+ 'tornado.escape',
'tornado.gen',
'tornado.httpclient',
'tornado.httpserver',
@@ -137,8 +138,8 @@ MOCK_MODULES = [
'pymongo',
'rabbitmq_server',
'redis',
- 'requests',
- 'requests.exceptions',
+ #'requests',
+ #'requests.exceptions',
'rpm',
'rpmUtils',
'rpmUtils.arch',
@@ -237,8 +238,7 @@ formulas_dir = os.path.join(os.pardir, docs_basepath, 'formulas')
# ----- Intersphinx Settings ------------------------------------------------>
intersphinx_mapping = {
- 'python2': ('http://docs.python.org/2', None),
- 'python3': ('http://docs.python.org/3', None)
+ 'python': ('https://docs.python.org/3', None)
}
# <---- Intersphinx Settings -------------------------------------------------
@@ -250,8 +250,8 @@ on_saltstack = 'SALT_ON_SALTSTACK' in os.environ
project = 'Salt'
version = salt.version.__version__
-latest_release = '2018.3.0' # latest release
-previous_release = '2017.7.5' # latest release from previous branch
+latest_release = '2018.3.2' # latest release
+previous_release = '2017.7.7' # latest release from previous branch
previous_release_dir = '2017.7' # path on web server for previous branch
next_release = '' # next release
next_release_dir = '' # path on web server for next release branch
@@ -357,9 +357,8 @@ rst_prolog = """\
# A shortcut for linking to tickets on the GitHub issue tracker
extlinks = {
'blob': ('https://github.com/saltstack/salt/blob/%s/%%s' % 'develop', None),
- 'download': ('https://cloud.github.com/downloads/saltstack/salt/%s', None),
- 'issue': ('https://github.com/saltstack/salt/issues/%s', 'issue '),
- 'pull': ('https://github.com/saltstack/salt/pull/%s', 'PR '),
+ 'issue': ('https://github.com/saltstack/salt/issues/%s', 'issue #'),
+ 'pull': ('https://github.com/saltstack/salt/pull/%s', 'PR #'),
'formula_url': ('https://github.com/saltstack-formulas/%s', ''),
}
diff --git a/doc/contents.rst b/doc/contents.rst
index a9d47810c9..e03490e840 100644
--- a/doc/contents.rst
+++ b/doc/contents.rst
@@ -7,6 +7,7 @@ Salt Table of Contents
.. toctree::
:maxdepth: 2
+ topics/index
topics/installation/index
topics/configuration/index
topics/using_salt
@@ -15,11 +16,15 @@ Salt Table of Contents
topics/utils/index
topics/event/index
topics/orchestrate/index
+ topics/solaris/index
topics/ssh/index
+ topics/thorium/index
topics/cloud/index
topics/proxyminion/index
topics/virt/index
ref/cli/index
+ ref/pillar/index
+ ref/tops/index
ref/index
topics/api
topics/topology/index
@@ -28,3 +33,4 @@ Salt Table of Contents
topics/development/index
topics/releases/index
topics/venafi/index
+ glossary
diff --git a/doc/faq.rst b/doc/faq.rst
index 28c298cda3..2894de2e41 100644
--- a/doc/faq.rst
+++ b/doc/faq.rst
@@ -148,22 +148,23 @@ Why aren't my custom modules/states/etc. available on my Minions?
-----------------------------------------------------------------
Custom modules are synced to Minions when
-:mod:`saltutil.sync_modules `,
-or :mod:`saltutil.sync_all ` is run.
-Custom modules are also synced by :mod:`state.apply` when run without
-any arguments.
+:py:func:`saltutil.sync_modules `,
+or :py:func:`saltutil.sync_all ` is run.
+Similarly, custom states are synced to Minions when :py:func:`saltutil.sync_states
+`, or :py:func:`saltutil.sync_all
+` is run.
-Similarly, custom states are synced to Minions
-when :mod:`state.apply `,
-:mod:`saltutil.sync_states `, or
-:mod:`saltutil.sync_all ` is run.
+They are both also synced when a :ref:`highstate ` is
+triggered.
-Custom states are also synced by :mod:`state.apply`
-when run without any arguments.
+As of the Fluorine release, as well as 2017.7.7 and 2018.3.2 in their
+respective release cycles, the ``sync`` argument to :py:func:`state.apply
+`/:py:func:`state.sls ` can
+be used to sync custom types when running individual SLS files.
Other custom types (renderers, outputters, etc.) have similar behavior, see the
-documentation for the :mod:`saltutil ` module for more
+documentation for the :py:func:`saltutil ` module for more
information.
:ref:`This reactor example ` can be used to automatically
diff --git a/doc/favicon.ico b/doc/favicon.ico
new file mode 100644
index 0000000000..e81db9c1d6
Binary files /dev/null and b/doc/favicon.ico differ
diff --git a/doc/man/salt-api.1 b/doc/man/salt-api.1
index 609e05e511..68e5da86a3 100644
--- a/doc/man/salt-api.1
+++ b/doc/man/salt-api.1
@@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
-.TH "SALT-API" "1" "May 07, 2018" "2017.7.6" "Salt"
+.TH "SALT-API" "1" "August 06, 2018" "2017.7.8" "Salt"
.SH NAME
salt-api \- salt-api Command
.
@@ -103,9 +103,9 @@ Logfile logging log level. One of \fBall\fP, \fBgarbage\fP, \fBtrace\fP,
.UNINDENT
.SH SEE ALSO
.sp
-\fBsalt\-api(7)\fP
-\fBsalt(7)\fP
-\fBsalt\-master(1)\fP
+\fIsalt\-api(7)\fP
+\fIsalt(7)\fP
+\fIsalt\-master(1)\fP
.SH AUTHOR
Thomas S. Hatch and many others, please see the Authors file
.\" Generated by docutils manpage writer.
diff --git a/doc/man/salt-call.1 b/doc/man/salt-call.1
index b2a28f25b9..c1d14463b4 100644
--- a/doc/man/salt-call.1
+++ b/doc/man/salt-call.1
@@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
-.TH "SALT-CALL" "1" "May 07, 2018" "2017.7.6" "Salt"
+.TH "SALT-CALL" "1" "August 06, 2018" "2017.7.8" "Salt"
.SH NAME
salt-call \- salt-call Documentation
.
@@ -265,9 +265,9 @@ output. Set to True or False. Default: none.
.UNINDENT
.SH SEE ALSO
.sp
-\fBsalt(1)\fP
-\fBsalt\-master(1)\fP
-\fBsalt\-minion(1)\fP
+\fIsalt(1)\fP
+\fIsalt\-master(1)\fP
+\fIsalt\-minion(1)\fP
.SH AUTHOR
Thomas S. Hatch and many others, please see the Authors file
.\" Generated by docutils manpage writer.
diff --git a/doc/man/salt-cloud.1 b/doc/man/salt-cloud.1
index 803e9761de..f39bfeb0dc 100644
--- a/doc/man/salt-cloud.1
+++ b/doc/man/salt-cloud.1
@@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
-.TH "SALT-CLOUD" "1" "May 07, 2018" "2017.7.6" "Salt"
+.TH "SALT-CLOUD" "1" "August 06, 2018" "2017.7.8" "Salt"
.SH NAME
salt-cloud \- Salt Cloud Command
.
@@ -387,10 +387,10 @@ salt\-cloud \-m /path/to/cloud.map \-Q
.UNINDENT
.SH SEE ALSO
.sp
-\fBsalt\-cloud(7)\fP
-\fBsalt(7)\fP
-\fBsalt\-master(1)\fP
-\fBsalt\-minion(1)\fP
+\fIsalt\-cloud(7)\fP
+\fIsalt(7)\fP
+\fIsalt\-master(1)\fP
+\fIsalt\-minion(1)\fP
.SH AUTHOR
Thomas S. Hatch and many others, please see the Authors file
.\" Generated by docutils manpage writer.
diff --git a/doc/man/salt-cp.1 b/doc/man/salt-cp.1
index 1e79b4fc7e..4f2e505ddc 100644
--- a/doc/man/salt-cp.1
+++ b/doc/man/salt-cp.1
@@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
-.TH "SALT-CP" "1" "May 07, 2018" "2017.7.6" "Salt"
+.TH "SALT-CP" "1" "August 06, 2018" "2017.7.8" "Salt"
.SH NAME
salt-cp \- salt-cp Documentation
.
@@ -201,9 +201,9 @@ New in version 2016.3.7,2016.11.6,2017.7.0.
.UNINDENT
.SH SEE ALSO
.sp
-\fBsalt(1)\fP
-\fBsalt\-master(1)\fP
-\fBsalt\-minion(1)\fP
+\fIsalt(1)\fP
+\fIsalt\-master(1)\fP
+\fIsalt\-minion(1)\fP
.SH AUTHOR
Thomas S. Hatch and many others, please see the Authors file
.\" Generated by docutils manpage writer.
diff --git a/doc/man/salt-key.1 b/doc/man/salt-key.1
index 7598fddc3f..810e7848e6 100644
--- a/doc/man/salt-key.1
+++ b/doc/man/salt-key.1
@@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
-.TH "SALT-KEY" "1" "May 07, 2018" "2017.7.6" "Salt"
+.TH "SALT-KEY" "1" "August 06, 2018" "2017.7.8" "Salt"
.SH NAME
salt-key \- salt-key Documentation
.
@@ -340,9 +340,9 @@ Auto\-create a signing key\-pair if it does not yet exist
.UNINDENT
.SH SEE ALSO
.sp
-\fBsalt(7)\fP
-\fBsalt\-master(1)\fP
-\fBsalt\-minion(1)\fP
+\fIsalt(7)\fP
+\fIsalt\-master(1)\fP
+\fIsalt\-minion(1)\fP
.SH AUTHOR
Thomas S. Hatch and many others, please see the Authors file
.\" Generated by docutils manpage writer.
diff --git a/doc/man/salt-master.1 b/doc/man/salt-master.1
index bf244bb04a..faf8bbb3a4 100644
--- a/doc/man/salt-master.1
+++ b/doc/man/salt-master.1
@@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
-.TH "SALT-MASTER" "1" "May 07, 2018" "2017.7.6" "Salt"
+.TH "SALT-MASTER" "1" "August 06, 2018" "2017.7.8" "Salt"
.SH NAME
salt-master \- salt-master Documentation
.
@@ -108,9 +108,9 @@ Logfile logging log level. One of \fBall\fP, \fBgarbage\fP, \fBtrace\fP,
.UNINDENT
.SH SEE ALSO
.sp
-\fBsalt(1)\fP
-\fBsalt(7)\fP
-\fBsalt\-minion(1)\fP
+\fIsalt(1)\fP
+\fIsalt(7)\fP
+\fIsalt\-minion(1)\fP
.SH AUTHOR
Thomas S. Hatch and many others, please see the Authors file
.\" Generated by docutils manpage writer.
diff --git a/doc/man/salt-minion.1 b/doc/man/salt-minion.1
index a40b3322c6..ac74530bdc 100644
--- a/doc/man/salt-minion.1
+++ b/doc/man/salt-minion.1
@@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
-.TH "SALT-MINION" "1" "May 07, 2018" "2017.7.6" "Salt"
+.TH "SALT-MINION" "1" "August 06, 2018" "2017.7.8" "Salt"
.SH NAME
salt-minion \- salt-minion Documentation
.
@@ -109,9 +109,9 @@ Logfile logging log level. One of \fBall\fP, \fBgarbage\fP, \fBtrace\fP,
.UNINDENT
.SH SEE ALSO
.sp
-\fBsalt(1)\fP
-\fBsalt(7)\fP
-\fBsalt\-master(1)\fP
+\fIsalt(1)\fP
+\fIsalt(7)\fP
+\fIsalt\-master(1)\fP
.SH AUTHOR
Thomas S. Hatch and many others, please see the Authors file
.\" Generated by docutils manpage writer.
diff --git a/doc/man/salt-proxy.1 b/doc/man/salt-proxy.1
index 13926d278b..6c62255624 100644
--- a/doc/man/salt-proxy.1
+++ b/doc/man/salt-proxy.1
@@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
-.TH "SALT-PROXY" "1" "May 07, 2018" "2017.7.6" "Salt"
+.TH "SALT-PROXY" "1" "August 06, 2018" "2017.7.8" "Salt"
.SH NAME
salt-proxy \- salt-proxy Documentation
.
@@ -116,10 +116,10 @@ Logfile logging log level. One of \fBall\fP, \fBgarbage\fP, \fBtrace\fP,
.UNINDENT
.SH SEE ALSO
.sp
-\fBsalt(1)\fP
-\fBsalt(7)\fP
-\fBsalt\-master(1)\fP
-\fBsalt\-minion(1)\fP
+\fIsalt(1)\fP
+\fIsalt(7)\fP
+\fIsalt\-master(1)\fP
+\fIsalt\-minion(1)\fP
.SH AUTHOR
Thomas S. Hatch and many others, please see the Authors file
.\" Generated by docutils manpage writer.
diff --git a/doc/man/salt-run.1 b/doc/man/salt-run.1
index 6c3266e53d..9acee7be69 100644
--- a/doc/man/salt-run.1
+++ b/doc/man/salt-run.1
@@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
-.TH "SALT-RUN" "1" "May 07, 2018" "2017.7.6" "Salt"
+.TH "SALT-RUN" "1" "August 06, 2018" "2017.7.8" "Salt"
.SH NAME
salt-run \- salt-run Documentation
.
@@ -114,9 +114,9 @@ Logfile logging log level. One of \fBall\fP, \fBgarbage\fP, \fBtrace\fP,
.UNINDENT
.SH SEE ALSO
.sp
-\fBsalt(1)\fP
-\fBsalt\-master(1)\fP
-\fBsalt\-minion(1)\fP
+\fIsalt(1)\fP
+\fIsalt\-master(1)\fP
+\fIsalt\-minion(1)\fP
.SH AUTHOR
Thomas S. Hatch and many others, please see the Authors file
.\" Generated by docutils manpage writer.
diff --git a/doc/man/salt-ssh.1 b/doc/man/salt-ssh.1
index 5b71974751..8faff2dd7d 100644
--- a/doc/man/salt-ssh.1
+++ b/doc/man/salt-ssh.1
@@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
-.TH "SALT-SSH" "1" "May 07, 2018" "2017.7.6" "Salt"
+.TH "SALT-SSH" "1" "August 06, 2018" "2017.7.8" "Salt"
.SH NAME
salt-ssh \- salt-ssh Documentation
.
@@ -348,9 +348,9 @@ output. Set to True or False. Default: none.
.UNINDENT
.SH SEE ALSO
.sp
-\fBsalt(7)\fP
-\fBsalt\-master(1)\fP
-\fBsalt\-minion(1)\fP
+\fIsalt(7)\fP
+\fIsalt\-master(1)\fP
+\fIsalt\-minion(1)\fP
.SH AUTHOR
Thomas S. Hatch and many others, please see the Authors file
.\" Generated by docutils manpage writer.
diff --git a/doc/man/salt-syndic.1 b/doc/man/salt-syndic.1
index 9689543fbd..ce07a9c044 100644
--- a/doc/man/salt-syndic.1
+++ b/doc/man/salt-syndic.1
@@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
-.TH "SALT-SYNDIC" "1" "May 07, 2018" "2017.7.6" "Salt"
+.TH "SALT-SYNDIC" "1" "August 06, 2018" "2017.7.8" "Salt"
.SH NAME
salt-syndic \- salt-syndic Documentation
.
@@ -110,9 +110,9 @@ Logfile logging log level. One of \fBall\fP, \fBgarbage\fP, \fBtrace\fP,
.UNINDENT
.SH SEE ALSO
.sp
-\fBsalt(1)\fP
-\fBsalt\-master(1)\fP
-\fBsalt\-minion(1)\fP
+\fIsalt(1)\fP
+\fIsalt\-master(1)\fP
+\fIsalt\-minion(1)\fP
.SH AUTHOR
Thomas S. Hatch and many others, please see the Authors file
.\" Generated by docutils manpage writer.
diff --git a/doc/man/salt-unity.1 b/doc/man/salt-unity.1
index abd27555dc..218f2003a3 100644
--- a/doc/man/salt-unity.1
+++ b/doc/man/salt-unity.1
@@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
-.TH "SALT-UNITY" "1" "May 07, 2018" "2017.7.6" "Salt"
+.TH "SALT-UNITY" "1" "August 06, 2018" "2017.7.8" "Salt"
.SH NAME
salt-unity \- salt-unity Command
.
@@ -50,17 +50,17 @@ invokes that script.
.SH OPTIONS
.SH SEE ALSO
.sp
-\fBsalt\-api(1)\fP
-\fBsalt\-call(1)\fP
-\fBsalt\-cloud(1)\fP
-\fBsalt\-cp(1)\fP
-\fBsalt\-key(1)\fP
-\fBsalt\-main(1)\fP
-\fBsalt\-master(1)\fP
-\fBsalt\-minion(1)\fP
-\fBsalt\-run(1)\fP
-\fBsalt\-ssh(1)\fP
-\fBsalt\-syndic(1)\fP
+\fIsalt\-api(1)\fP
+\fIsalt\-call(1)\fP
+\fIsalt\-cloud(1)\fP
+\fIsalt\-cp(1)\fP
+\fIsalt\-key(1)\fP
+\fIsalt\-main(1)\fP
+\fIsalt\-master(1)\fP
+\fIsalt\-minion(1)\fP
+\fIsalt\-run(1)\fP
+\fIsalt\-ssh(1)\fP
+\fIsalt\-syndic(1)\fP
.SH AUTHOR
Thomas S. Hatch and many others, please see the Authors file
.\" Generated by docutils manpage writer.
diff --git a/doc/man/salt.1 b/doc/man/salt.1
index dd8b388fe0..e033cc0437 100644
--- a/doc/man/salt.1
+++ b/doc/man/salt.1
@@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
-.TH "SALT" "1" "May 07, 2018" "2017.7.6" "Salt"
+.TH "SALT" "1" "August 06, 2018" "2017.7.8" "Salt"
.SH NAME
salt \- salt
.
@@ -95,16 +95,6 @@ the started execution and complete.
.UNINDENT
.INDENT 0.0
.TP
-.B \-\-state\-output=STATE_OUTPUT
-New in version 0.17.
-
-.sp
-Override the configured \fBstate_output\fP value for minion output. One of
-\fBfull\fP, \fBterse\fP, \fBmixed\fP, \fBchanges\fP or \fBfilter\fP\&. Default:
-\fBfull\fP\&.
-.UNINDENT
-.INDENT 0.0
-.TP
.B \-\-subset=SUBSET
Execute the routine on a random subset of the targeted minions. The
minions will be verified that they have the named function before
@@ -344,9 +334,9 @@ output. Set to True or False. Default: none.
.UNINDENT
.SH SEE ALSO
.sp
-\fBsalt(7)\fP
-\fBsalt\-master(1)\fP
-\fBsalt\-minion(1)\fP
+\fIsalt(7)\fP
+\fIsalt\-master(1)\fP
+\fIsalt\-minion(1)\fP
.SH AUTHOR
Thomas S. Hatch and many others, please see the Authors file
.\" Generated by docutils manpage writer.
diff --git a/doc/man/salt.7 b/doc/man/salt.7
index d3220f6452..aeb69051f3 100644
--- a/doc/man/salt.7
+++ b/doc/man/salt.7
@@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
-.TH "SALT" "7" "May 07, 2018" "2017.7.6" "Salt"
+.TH "SALT" "7" "August 06, 2018" "2017.7.8" "Salt"
.SH NAME
salt \- Salt Documentation
.
@@ -30,6 +30,168 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
+.SH INTRODUCTION TO SALT
+We’re not just talking about NaCl..SS The 30 second summary
+.sp
+Salt is:
+.INDENT 0.0
+.IP \(bu 2
+a configuration management system, capable of maintaining remote nodes
+in defined states (for example, ensuring that specific packages are installed and
+specific services are running)
+.IP \(bu 2
+a distributed remote execution system used to execute commands and
+query data on remote nodes, either individually or by arbitrary
+selection criteria
+.UNINDENT
+.sp
+It was developed in order to bring the best solutions found in the
+world of remote execution together and make them better, faster, and more
+malleable. Salt accomplishes this through its ability to handle large loads of
+information, and not just dozens but hundreds and even thousands of individual
+servers quickly through a simple and manageable interface.
+.SS Simplicity
+.sp
+Providing versatility between massive scale deployments and smaller systems may seem
+daunting, but Salt is very simple to set up and maintain, regardless of the
+size of the project. The architecture of Salt is designed to work with any
+number of servers, from a handful of local network systems to international
+deployments across different data centers. The topology is a simple
+server/client model with the needed functionality built into a single set of
+daemons. While the default configuration will work with little to no
+modification, Salt can be fine tuned to meet specific needs.
+.SS Parallel execution
+.sp
+The core functions of Salt:
+.INDENT 0.0
+.IP \(bu 2
+enable commands to remote systems to be called in parallel rather than serially
+.IP \(bu 2
+use a secure and encrypted protocol
+.IP \(bu 2
+use the smallest and fastest network payloads possible
+.IP \(bu 2
+provide a simple programming interface
+.UNINDENT
+.sp
+Salt also introduces more granular controls to the realm of remote
+execution, allowing systems to be targeted not just by hostname, but
+also by system properties.
+.SS Builds on proven technology
+.sp
+Salt takes advantage of a number of technologies and techniques. The
+networking layer is built with the excellent \fI\%ZeroMQ\fP networking
+library, so the Salt daemon includes a viable and transparent AMQ
+broker. Salt uses public keys for authentication with the master
+daemon, then uses faster \fI\%AES\fP encryption for payload communication;
+authentication and encryption are integral to Salt. Salt takes
+advantage of communication via \fI\%msgpack\fP, enabling fast and light
+network traffic.
+.SS Python client interface
+.sp
+In order to allow for simple expansion, Salt execution routines can be written
+as plain Python modules. The data collected from Salt executions can be sent
+back to the master server, or to any arbitrary program. Salt can be called from
+a simple Python API, or from the command line, so that Salt can be used to
+execute one\-off commands as well as operate as an integral part of a larger
+application.
+.SS Fast, flexible, scalable
+.sp
+The result is a system that can execute commands at high speed on
+target server groups ranging from one to very many servers. Salt is
+very fast, easy to set up, amazingly malleable and provides a single
+remote execution architecture that can manage the diverse
+requirements of any number of servers. The Salt infrastructure
+brings together the best of the remote execution world, amplifies its
+capabilities and expands its range, resulting in a system that is as
+versatile as it is practical, suitable for any network.
+.SS Open
+.sp
+Salt is developed under the \fI\%Apache 2.0 license\fP, and can be used for
+open and proprietary projects. Please submit your expansions back to
+the Salt project so that we can all benefit together as Salt grows.
+Please feel free to sprinkle Salt around your systems and let the
+deliciousness come forth.
+.SS Salt Community
+.sp
+Join the Salt!
+.sp
+There are many ways to participate in and communicate with the Salt community.
+.sp
+Salt has an active IRC channel and a mailing list.
+.SS Mailing List
+.sp
+Join the \fI\%salt\-users mailing list\fP\&. It is the best place to ask questions
+about Salt and see whats going on with Salt development! The Salt mailing list
+is hosted by Google Groups. It is open to new members.
+.SS IRC
+.sp
+The \fB#salt\fP IRC channel is hosted on the popular \fI\%Freenode\fP network. You
+can use the \fI\%Freenode webchat client\fP right from your browser.
+.sp
+\fI\%Logs of the IRC channel activity\fP are being collected courtesy of Moritz Lenz.
+.sp
+If you wish to discuss the development of Salt itself join us in
+\fB#salt\-devel\fP\&.
+.SS Follow on Github
+.sp
+The Salt code is developed via Github. Follow Salt for constant updates on what
+is happening in Salt development:
+.sp
+\fI\%https://github.com/saltstack/salt\fP
+.SS Blogs
+.sp
+SaltStack Inc. keeps a \fI\%blog\fP with recent news and advancements:
+.sp
+\fI\%http://www.saltstack.com/blog/\fP
+.SS Example Salt States
+.sp
+The official \fBsalt\-states\fP repository is:
+\fI\%https://github.com/saltstack/salt\-states\fP
+.sp
+A few examples of salt states from the community:
+.INDENT 0.0
+.IP \(bu 2
+\fI\%https://github.com/blast\-hardcheese/blast\-salt\-states\fP
+.IP \(bu 2
+\fI\%https://github.com/kevingranade/kevingranade\-salt\-state\fP
+.IP \(bu 2
+\fI\%https://github.com/uggedal/states\fP
+.IP \(bu 2
+\fI\%https://github.com/mattmcclean/salt\-openstack/tree/master/salt\fP
+.IP \(bu 2
+\fI\%https://github.com/rentalita/ubuntu\-setup/\fP
+.IP \(bu 2
+\fI\%https://github.com/brutasse/states\fP
+.IP \(bu 2
+\fI\%https://github.com/bclermont/states\fP
+.IP \(bu 2
+\fI\%https://github.com/pcrews/salt\-data\fP
+.UNINDENT
+.SS Follow on ohloh
+.sp
+\fI\%https://www.ohloh.net/p/salt\fP
+.SS Other community links
+.INDENT 0.0
+.IP \(bu 2
+\fI\%Salt Stack Inc.\fP
+.IP \(bu 2
+\fI\%Subreddit\fP
+.IP \(bu 2
+\fI\%Google+\fP
+.IP \(bu 2
+\fI\%YouTube\fP
+.IP \(bu 2
+\fI\%Facebook\fP
+.IP \(bu 2
+\fI\%Twitter\fP
+.IP \(bu 2
+\fI\%Wikipedia page\fP
+.UNINDENT
+.SS Hack the Source
+.sp
+If you want to get involved with the development of source code or the
+documentation efforts, please review the contributing documentation!
.SH INSTALLATION
.sp
This section contains instructions to install Salt. If you are setting up your
@@ -170,7 +332,7 @@ Now go to the Configuring Salt page.
.sp
Debian GNU/Linux distribution and some derivatives such as Raspbian already
have included Salt packages to their repositories. However, current stable
-release codenamed "Jessie" contains old outdated Salt release. It is
+Debian release contains old outdated Salt releases. It is
recommended to use SaltStack repository for Debian as described
\fI\%below\fP\&.
.sp
@@ -193,11 +355,13 @@ Regular security support for Debian 7 ended on April 25th 2016. As a result,
.UNINDENT
.SS Installation from the Debian / Raspbian Official Repository
.sp
-Stretch (Testing) and Sid (Unstable) distributions are already contain mostly
-up\-to\-date Salt packages built by Debian Salt Team. You can install Salt
-components directly from Debian.
+The Debian distributions contain mostly old Salt packages
+built by the Debian Salt Team. You can install Salt
+components directly from Debian but it is recommended to
+use the instructions above for the packages from the official
+Salt repository.
.sp
-On Jessie (Stable) there is an option to install Salt minion from Stretch with
+On Jessie there is an option to install Salt minion from Stretch with
\fIpython\-tornado\fP dependency from \fIjessie\-backports\fP repositories.
.sp
To install fresh release of Salt minion on Jessie:
@@ -270,7 +434,7 @@ apt\-get install python\-zmq python\-tornado/stretch salt\-common/stretch
.UNINDENT
.UNINDENT
.IP 4. 3
-Install Salt minion package from Stretch:
+Install Salt minion package from Latest Debian Release:
.INDENT 3.0
.INDENT 3.5
.sp
@@ -3434,7 +3598,7 @@ Here\(aqs a brief overview of a Salt cluster:
.INDENT 0.0
.IP \(bu 2
Salt works by having a "master" server sending commands to one or multiple
-"minion" servers [1]\&. The master server is the "command center". It is
+"minion" servers. The master server is the "command center". It is
going to be the place where you store your configuration files, aka: "which
server is the db, which is the web server, and what libraries and software
they should have installed". The minions receive orders from the master.
@@ -3469,11 +3633,16 @@ it also contains some Salt configuration. More on that in step 3. Also
note that all configuration files are YAML files. So indentation matters.
.UNINDENT
.UNINDENT
-.IP [1] 5
+.sp
+\fBNOTE:\fP
+.INDENT 0.0
+.INDENT 3.5
Salt also works with "masterless" configuration where a minion is
autonomous (in which case salt can be seen as a local configuration tool),
or in "multiple master" configuration. See the documentation for more on
that.
+.UNINDENT
+.UNINDENT
.SS Before Digging In, The Architecture Of The Salt Cluster
.SS Salt Master
.sp
@@ -3487,7 +3656,7 @@ Virtual Machine running on the Mac, using VirtualBox. It will run an Ubuntu
distribution.
.SS Step 1 \- Configuring The Salt Master On Your Mac
.sp
-\fI\%official documentation\fP
+\fI\%Official Documentation\fP
.sp
Because Salt has a lot of dependencies that are not built in macOS, we will use
Homebrew to install Salt. Homebrew is a package manager for Mac, it\(aqs great, use
@@ -3524,6 +3693,7 @@ dialog box to display hidden files and folders, such as .profile.
.SS Install Homebrew
.sp
Install Homebrew here \fI\%http://brew.sh/\fP
+.sp
Or just type
.INDENT 0.0
.INDENT 3.5
@@ -3637,6 +3807,7 @@ it running on a terminal to monitor the activity.
.UNINDENT
.sp
Now that the master is set, let\(aqs configure a minion on a VM.
+.SS Step 2 \- Configuring The Minion VM
.sp
The Salt minion is going to run on a Virtual Machine. There are a lot of
software options that let you run virtual machines on a mac, But for this
@@ -3815,6 +3986,7 @@ Once you\(aqre done, end the ssh session by typing \fBexit\fP\&.
.UNINDENT
.sp
It\(aqs now time to connect the VM to the salt master
+.SS Step 3 \- Connecting Master and Minion
.SS Creating The Minion Configuration File
.sp
Create the \fB/etc/salt/minion\fP file. In that file, put the
@@ -3941,6 +4113,7 @@ sudo salt \(aq*\(aq test.ping
.sp
You should see your minion answering the ping. It\(aqs now time to do some
configuration.
+.SS Step 4 \- Configure Services to Install On the Minion
.sp
In this step we\(aqll use the Salt master to instruct our minion to install
Nginx.
@@ -4471,11 +4644,7 @@ learning how to write more complex states\&.
Salt should run on any Unix\-like platform so long as the dependencies are met.
.INDENT 0.0
.IP \(bu 2
-
-.nf
-\(gaPython 2.7\(ga_
-.fi
- >= 2.7 <3.0
+\fI\%Python 2.7\fP >= 2.7 <3.0
.IP \(bu 2
\fI\%msgpack\-python\fP \- High\-performance message interchange format
.IP \(bu 2
@@ -5382,24 +5551,6 @@ max_event_size: 1048576
.fi
.UNINDENT
.UNINDENT
-.SS \fBping_on_rotate\fP
-.sp
-New in version 2014.7.0.
-
-.sp
-Default: \fBFalse\fP
-.sp
-By default, the master AES key rotates every 24 hours. The next command
-following a key rotation will trigger a key refresh from the minion which may
-result in minions which do not respond to the first command after a key refresh.
-.sp
-To tell the master to ping all minions immediately after an AES key refresh, set
-ping_on_rotate to \fBTrue\fP\&. This should mitigate the issue where a minion does not
-appear to initially respond after a key is rotated.
-.sp
-Note that ping_on_rotate may cause high load on the master immediately after
-the key rotation event as minions reconnect. Consider this carefully if this
-salt master is managing a large number of minions.
.SS \fBmaster_job_cache\fP
.sp
New in version 2014.7.0.
@@ -5531,7 +5682,7 @@ Changes the underlying transport layer. ZeroMQ is the recommended transport
while additional transport layers are under development. Supported values are
\fBzeromq\fP, \fBraet\fP (experimental), and \fBtcp\fP (experimental). This setting has
a significant impact on performance and should not be changed unless you know
-what you are doing! Transports are explained in Salt Transports\&.
+what you are doing!
.INDENT 0.0
.INDENT 3.5
.sp
@@ -5546,9 +5697,10 @@ transport: zeromq
.sp
Default: \fB{}\fP
.sp
-(experimental) Starts multiple transports and overrides options for each transport with the provided dictionary
-This setting has a significant impact on performance and should not be changed unless you know
-what you are doing! Transports are explained in Salt Transports\&. The following example shows how to start a TCP transport alongside a ZMQ transport.
+(experimental) Starts multiple transports and overrides options for each
+transport with the provided dictionary This setting has a significant impact on
+performance and should not be changed unless you know what you are doing! The
+following example shows how to start a TCP transport alongside a ZMQ transport.
.INDENT 0.0
.INDENT 3.5
.sp
@@ -5704,6 +5856,26 @@ minion_data_cache_events: True
.UNINDENT
.UNINDENT
.SS Salt\-SSH Configuration
+.SS \fBroster_defaults\fP
+.sp
+New in version 2017.7.0.
+
+.sp
+Default settings which will be inherited by all rosters.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+roster_defaults:
+ user: daniel
+ sudo: True
+ priv: /root/.ssh/id_rsa
+ tty: True
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
.SS \fBroster_file\fP
.sp
Default: \fB/etc/salt/roster\fP
@@ -6347,7 +6519,7 @@ ssl:
.fi
.UNINDENT
.UNINDENT
-.SS \fBallow_minion_key_revoke\fP
+.SS \fBpreserve_minion_cache\fP
.sp
Default: \fBFalse\fP
.sp
@@ -6379,7 +6551,7 @@ the master will drop the request and the minion\(aqs key will remain accepted.
.sp
.nf
.ft C
-rotate_aes_key: True
+allow_minion_key_revoke: False
.ft P
.fi
.UNINDENT
@@ -9038,15 +9210,15 @@ strategy between different sources. It accepts 5 values:
.INDENT 0.0
.IP \(bu 2
\fBnone\fP:
-.UNINDENT
.sp
-New in version 2016.3.4: It will not do any merging at all and only parse the pillar data from the passed environment and \(aqbase\(aq if no environment was specified.
+It will not do any merging at all and only parse the pillar data from the passed environment and \(aqbase\(aq if no environment was specified.
+.sp
+New in version 2016.3.4.
-.INDENT 0.0
.IP \(bu 2
\fBrecurse\fP:
.sp
-it will merge recursively mapping of data. For example, theses 2 sources:
+It will recursively merge data. For example, theses 2 sources:
.INDENT 2.0
.INDENT 3.5
.sp
@@ -9354,6 +9526,16 @@ reactor_refresh_interval: 60
Default: \fB10\fP
.sp
The number of workers for the runner/wheel in the reactor.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+reactor_worker_threads: 10
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
.SS \fBreactor_worker_hwm\fP
.sp
Default: \fB10000\fP
@@ -10797,7 +10979,7 @@ Default: \fBFalse\fP
.sp
If \fI\%master\fP is a list of addresses and :conf_minion\(gamaster_type\(ga
is \fBfailover\fP, shuffle them before trying to connect to distribute the
-minions over all available masters. This uses Python\(aqs \fI\%random.shuffle\fP method.
+minions over all available masters. This uses Python\(aqs \fBrandom.shuffle\fP method.
.INDENT 0.0
.INDENT 3.5
.sp
@@ -10814,7 +10996,7 @@ Default: \fBFalse\fP
.sp
If \fI\%master\fP is a list of addresses, and :conf_minion\(gamaster_type\(ga
is set to \fBfailover\fP shuffle them before trying to connect to distribute the
-minions over all available masters. This uses Python\(aqs \fI\%random.shuffle\fP method.
+minions over all available masters. This uses Python\(aqs \fBrandom.shuffle\fP method.
.INDENT 0.0
.INDENT 3.5
.sp
@@ -11007,11 +11189,7 @@ New in version 0.17.2.
.sp
Default: \fBTrue\fP
.sp
-Caches the minion id to a file when the minion\(aqs
-.nf
-:minion_conf:\(gaid\(ga
-.fi
- is not
+Caches the minion id to a file when the minion\(aqs \fI\%id\fP is not
statically defined in the minion config. This setting prevents potential
problems when automatic minion id resolution changes, which can cause the
minion to lose connection with the master. To turn off minion id caching,
@@ -11465,7 +11643,7 @@ is set in the \fI\%master_type\fP configuration, this value is the number
of attempts for each set of masters. In this mode, it will cycle through the list
of masters for each attempt.
.sp
-\fBmaster_tries\fP is different than \fBauth_tries\fP because \fBauth_tries\fP
+\fBmaster_tries\fP is different than \fI\%auth_tries\fP because \fBauth_tries\fP
attempts to retry auth attempts with a single master. \fBauth_tries\fP is under the
assumption that you can connect to the master but not gain authorization from it.
\fBmaster_tries\fP will still cycle through all of the masters in a given try, so it
@@ -11788,7 +11966,7 @@ Changes the underlying transport layer. ZeroMQ is the recommended transport
while additional transport layers are under development. Supported values are
\fBzeromq\fP, \fBraet\fP (experimental), and \fBtcp\fP (experimental). This setting has
a significant impact on performance and should not be changed unless you know
-what you are doing! Transports are explained in Salt Transports\&.
+what you are doing!
.INDENT 0.0
.INDENT 3.5
.sp
@@ -11875,6 +12053,48 @@ proxy_password: obolus
.fi
.UNINDENT
.UNINDENT
+.SS Docker Configuration
+.SS \fBdocker.update_mine\fP
+.sp
+New in version 2017.7.8,2018.3.3.
+
+.sp
+Changed in version Fluorine: The default value is now \fBFalse\fP
+
+.sp
+Default: \fBTrue\fP
+.sp
+If enabled, when containers are added, removed, stopped, started, etc., the
+mine will be updated with the results of \fBdocker.ps
+verbose=True all=True host=True\fP\&. This mine data is
+used by \fBmine.get_docker\fP\&. Set this
+option to \fBFalse\fP to keep Salt from updating the mine with this information.
+.sp
+\fBNOTE:\fP
+.INDENT 0.0
+.INDENT 3.5
+This option can also be set in Grains or Pillar data, with Grains
+overriding Pillar and the minion config file overriding Grains.
+.UNINDENT
+.UNINDENT
+.sp
+\fBNOTE:\fP
+.INDENT 0.0
+.INDENT 3.5
+Disabling this will of course keep \fBmine.get_docker\fP from returning any information for a given
+minion.
+.UNINDENT
+.UNINDENT
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+docker.update_mine: False
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
.SS Minion Module Management
.SS \fBdisable_modules\fP
.sp
@@ -12098,11 +12318,7 @@ providers:
Default: \fB\-1\fP
.sp
Specify a max size (in bytes) for modules on import. This feature is currently
-only supported on
-.nf
-*
-.fi
-nix operating systems and requires psutil.
+only supported on *NIX operating systems and requires psutil.
.INDENT 0.0
.INDENT 3.5
.sp
@@ -13202,6 +13418,16 @@ reactor_refresh_interval: 60
Default: \fB10\fP
.sp
The number of workers for the runner/wheel in the reactor.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+reactor_worker_threads: 10
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
.SS \fBreactor_worker_hwm\fP
.sp
Default: \fB10000\fP
@@ -18346,7 +18572,7 @@ management.
.sp
The default job cache is a temporary cache and jobs will be stored for 24
hours. If the default cache needs to store jobs for a different period the
-time can be easily adjusted by changing the \fIkeep_jobs\fP parameter in the
+time can be easily adjusted by changing the \fBkeep_jobs\fP parameter in the
Salt Master configuration file. The value passed in is measured via hours:
.INDENT 0.0
.INDENT 3.5
@@ -18375,7 +18601,7 @@ checking for and preventing JID collisions.
The default location for the job cache is in the \fB/var/cache/salt/master/jobs/\fP
directory.
.sp
-Setting the \fBjob_cache\(ga\fP to \fBFalse\fP in addition to setting
+Setting the \fBjob_cache\fP to \fBFalse\fP in addition to setting
the \fBkeep_jobs\fP option to a smaller value, such as \fB1\fP, in the Salt
Master configuration file will reduce the size of the Default Job Cache, and thus
the burden on the Salt Master.
@@ -18631,9 +18857,9 @@ example, setting \fBlog_level: error\fP will log statements at \fBerror\fP,
\fBquiet\fP level.
.sp
Most of the logging levels are defined by default in Python\(aqs logging library
-and can be found in the official \fI\%Python documentation\fP\&. Salt uses some more
-levels in addition to the standard levels. All levels available in salt are
-shown in the table below.
+and can be found in the official \fI\%Python documentation\fP\&.
+Salt uses some more levels in addition to the standard levels. All levels
+available in salt are shown in the table below.
.sp
\fBNOTE:\fP
.INDENT 0.0
@@ -18744,10 +18970,19 @@ The log records can be sent to a regular file, local path name, or network
location. Remote logging works best when configured to use rsyslogd(8) (e.g.:
\fBfile:///dev/log\fP), with rsyslogd(8) configured for network logging. The
format for remote addresses is:
-\fB://:/\fP\&. Where
-\fBlog\-facility\fP is the symbolic name of a syslog facility as defined in the
-SysLogHandler documentation . It defaults to
-\fBLOG_USER\fP\&.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+://:/
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Where \fBlog\-facility\fP is the symbolic name of a syslog facility as defined in
+the \fI\%SysLogHandler documentation\fP\&. It defaults to \fBLOG_USER\fP\&.
.sp
Default: Dependent of the binary being executed, for example, for
\fBsalt\-master\fP, \fB/var/log/salt/master\fP\&.
@@ -18851,7 +19086,7 @@ log_level_logfile: warning
Default: \fB%H:%M:%S\fP
.sp
The date and time format used in console log messages. Allowed date/time
-formatting can be seen on \fI\%time.strftime\fP\&.
+formatting matches those used in \fI\%time.strftime()\fP\&.
.INDENT 0.0
.INDENT 3.5
.sp
@@ -18867,7 +19102,7 @@ log_datefmt: \(aq%H:%M:%S\(aq
Default: \fB%Y\-%m\-%d %H:%M:%S\fP
.sp
The date and time format used in log file messages. Allowed date/time
-formatting can be seen on \fI\%time.strftime\fP\&.
+formatting matches those used in \fI\%time.strftime()\fP\&.
.INDENT 0.0
.INDENT 3.5
.sp
@@ -18883,8 +19118,8 @@ log_datefmt_logfile: \(aq%Y\-%m\-%d %H:%M:%S\(aq
Default: \fB[%(levelname)\-8s] %(message)s\fP
.sp
The format of the console logging messages. All standard python logging
-\fI\%LogRecord attributes\fP can be used. Salt
-also provides these custom LogRecord attributes to colorize console log output:
+\fI\%LogRecord\fP attributes can be used. Salt also provides these
+custom LogRecord attributes to colorize console log output:
.INDENT 0.0
.INDENT 3.5
.sp
@@ -18923,9 +19158,9 @@ log_fmt_console: \(aq[%(levelname)\-8s] %(message)s\(aq
Default: \fB%(asctime)s,%(msecs)03d [%(name)\-17s][%(levelname)\-8s] %(message)s\fP
.sp
The format of the log file logging messages. All standard python logging
-\fI\%LogRecord attributes\fP can be used. Salt
-also provides these custom LogRecord attributes that include padding and
-enclosing brackets \fB[\fP and \fB]\fP:
+\fI\%LogRecord\fP attributes can be used. Salt also provides
+these custom LogRecord attributes that include padding and enclosing brackets
+\fB[\fP and \fB]\fP:
.INDENT 0.0
.INDENT 3.5
.sp
@@ -18973,6 +19208,390 @@ log_granular_levels:
Besides the internal logging handlers used by salt, there are some external
which can be used, see the external logging handlers
document.
+.SS External Logging Handlers
+.TS
+center;
+|l|l|.
+_
+T{
+\fBfluent_mod\fP
+T} T{
+Fluent Logging Handler
+T}
+_
+T{
+\fBlog4mongo_mod\fP
+T} T{
+Log4Mongo Logging Handler
+T}
+_
+T{
+\fBlogstash_mod\fP
+T} T{
+Logstash Logging Handler
+T}
+_
+T{
+\fBsentry_mod\fP
+T} T{
+Sentry Logging Handler
+T}
+_
+.TE
+.SS salt.log.handlers.fluent_mod
+.SS Fluent Logging Handler
+.sp
+New in version 2015.8.0.
+
+.sp
+This module provides some \fI\%fluentd\fP logging handlers.
+.SS Fluent Logging Handler
+.sp
+In the salt configuration file:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+fluent_handler:
+ host: localhost
+ port: 24224
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+In the \fI\%fluentd\fP configuration file:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.SS Log Level
+.sp
+The \fBfluent_handler\fP configuration section accepts an additional setting
+\fBlog_level\fP\&. If not set, the logging level used will be the one defined
+for \fBlog_level\fP in the global configuration file section.
+.INDENT 0.0
+.INDENT 3.5
+.IP "Inspiration"
+.sp
+This work was inspired in \fI\%fluent\-logger\-python\fP
+.UNINDENT
+.UNINDENT
+.SS salt.log.handlers.log4mongo_mod
+.SS Log4Mongo Logging Handler
+.sp
+This module provides a logging handler for sending salt logs to MongoDB
+.SS Configuration
+.sp
+In the salt configuration file (e.g. /etc/salt/{master,minion}):
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+log4mongo_handler:
+ host: mongodb_host
+ port: 27017
+ database_name: logs
+ collection: salt_logs
+ username: logging
+ password: reindeerflotilla
+ write_concern: 0
+ log_level: warning
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.SS Log Level
+.sp
+If not set, the log_level will be set to the level defined in the global
+configuration file setting.
+.INDENT 0.0
+.INDENT 3.5
+.IP "Inspiration"
+.sp
+This work was inspired by the Salt logging handlers for LogStash and
+Sentry and by the log4mongo Python implementation.
+.UNINDENT
+.UNINDENT
+.SS salt.log.handlers.logstash_mod
+.SS Logstash Logging Handler
+.sp
+New in version 0.17.0.
+
+.sp
+This module provides some \fI\%Logstash\fP logging handlers.
+.SS UDP Logging Handler
+.sp
+For versions of \fI\%Logstash\fP before 1.2.0:
+.sp
+In the salt configuration file:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+logstash_udp_handler:
+ host: 127.0.0.1
+ port: 9999
+ version: 0
+ msg_type: logstash
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+In the \fI\%Logstash\fP configuration file:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+input {
+ udp {
+ type => "udp\-type"
+ format => "json_event"
+ }
+}
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+For version 1.2.0 of \fI\%Logstash\fP and newer:
+.sp
+In the salt configuration file:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+logstash_udp_handler:
+ host: 127.0.0.1
+ port: 9999
+ version: 1
+ msg_type: logstash
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+In the \fI\%Logstash\fP configuration file:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+input {
+ udp {
+ port => 9999
+ codec => json
+ }
+}
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Please read the \fI\%UDP input\fP configuration page for additional information.
+.SS ZeroMQ Logging Handler
+.sp
+For versions of \fI\%Logstash\fP before 1.2.0:
+.sp
+In the salt configuration file:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+logstash_zmq_handler:
+ address: tcp://127.0.0.1:2021
+ version: 0
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+In the \fI\%Logstash\fP configuration file:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+input {
+ zeromq {
+ type => "zeromq\-type"
+ mode => "server"
+ topology => "pubsub"
+ address => "tcp://0.0.0.0:2021"
+ charset => "UTF\-8"
+ format => "json_event"
+ }
+}
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+For version 1.2.0 of \fI\%Logstash\fP and newer:
+.sp
+In the salt configuration file:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+logstash_zmq_handler:
+ address: tcp://127.0.0.1:2021
+ version: 1
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+In the \fI\%Logstash\fP configuration file:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+input {
+ zeromq {
+ topology => "pubsub"
+ address => "tcp://0.0.0.0:2021"
+ codec => json
+ }
+}
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Please read the \fI\%ZeroMQ input\fP configuration page for additional
+information.
+.INDENT 0.0
+.INDENT 3.5
+.IP "Important Logstash Setting"
+.sp
+One of the most important settings that you should not forget on your
+\fI\%Logstash\fP configuration file regarding these logging handlers is
+\fBformat\fP\&.
+Both the \fIUDP\fP and \fIZeroMQ\fP inputs need to have \fBformat\fP as
+\fBjson_event\fP which is what we send over the wire.
+.UNINDENT
+.UNINDENT
+.SS Log Level
+.sp
+Both the \fBlogstash_udp_handler\fP and the \fBlogstash_zmq_handler\fP
+configuration sections accept an additional setting \fBlog_level\fP\&. If not
+set, the logging level used will be the one defined for \fBlog_level\fP in
+the global configuration file section.
+.SS HWM
+.sp
+The \fI\%high water mark\fP for the ZMQ socket setting. Only applicable for the
+\fBlogstash_zmq_handler\fP\&.
+.INDENT 0.0
+.INDENT 3.5
+.IP "Inspiration"
+.sp
+This work was inspired in \fI\%pylogstash\fP, \fI\%python\-logstash\fP, \fI\%canary\fP
+and the \fI\%PyZMQ logging handler\fP\&.
+.UNINDENT
+.UNINDENT
+.SS salt.log.handlers.sentry_mod
+.SS Sentry Logging Handler
+.sp
+New in version 0.17.0.
+
+.sp
+This module provides a \fI\%Sentry\fP logging handler.
+.INDENT 0.0
+.INDENT 3.5
+.IP "Note"
+.sp
+The \fI\%Raven\fP library needs to be installed on the system for this
+logging handler to be available.
+.UNINDENT
+.UNINDENT
+.sp
+Configuring the python \fI\%Sentry\fP client, \fI\%Raven\fP, should be done under the
+\fBsentry_handler\fP configuration key. Additional \fIcontext\fP may be provided
+for corresponding grain item(s).
+At the bare minimum, you need to define the \fI\%DSN\fP\&. As an example:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+sentry_handler:
+ dsn: https://pub\-key:secret\-key@app.getsentry.com/app\-id
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+More complex configurations can be achieved, for example:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+sentry_handler:
+ servers:
+ \- https://sentry.example.com
+ \- http://192.168.1.1
+ project: app\-id
+ public_key: deadbeefdeadbeefdeadbeefdeadbeef
+ secret_key: beefdeadbeefdeadbeefdeadbeefdead
+ context:
+ \- os
+ \- master
+ \- saltversion
+ \- cpuarch
+ \- ec2.tags.environment
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+All the client configuration keys are supported, please see the
+\fI\%Raven client documentation\fP\&.
+.sp
+The default logging level for the sentry handler is \fBERROR\fP\&. If you wish
+to define a different one, define \fBlog_level\fP under the
+\fBsentry_handler\fP configuration key:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+sentry_handler:
+ dsn: https://pub\-key:secret\-key@app.getsentry.com/app\-id
+ log_level: warning
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+The available log levels are those also available for the salt \fBcli\fP
+tools and configuration; \fBsalt \-\-help\fP should give you the required
+information.
+.SS Threaded Transports
+.sp
+Raven\(aqs documents rightly suggest using its threaded transport for
+critical applications. However, don\(aqt forget that if you start having
+troubles with Salt after enabling the threaded transport, please try
+switching to a non\-threaded transport to see if that fixes your problem.
.SS Salt File Server
.sp
Salt comes with a simple file server suitable for distributing files to the
@@ -19616,17 +20235,13 @@ following these instructions will install \fI\%libgit2\fP and \fI\%pygit2\fP wit
packages. Additionally, keep in mind that \fI\%SSH authentication in pygit2\fP requires \fI\%libssh2\fP (\fInot\fP libssh) development
libraries to be present before \fI\%libgit2\fP is built. On some Debian\-based distros
\fBpkg\-config\fP is also required to link \fI\%libgit2\fP with libssh2.
-.. note:
+.sp
+\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
-.sp
-.nf
-.ft C
If you are receiving the error "Unsupported URL Protocol" in the Salt Master
log when making a connection using SSH, review the libssh2 details listed
above.
-.ft P
-.fi
.UNINDENT
.UNINDENT
.sp
@@ -20170,9 +20785,8 @@ Global per\-saltenv configuration (defined in \fBgitfs_saltenv\fP)
.nf
.ft C
gitfs_saltenv:
- \- saltenv:
- \- dev:
- \- mountpoint: salt://bar
+ \- dev:
+ \- mountpoint: salt://bar
.ft P
.fi
.UNINDENT
@@ -20285,14 +20899,19 @@ gitfs_mountpoint: salt://webapps/foo/files
.UNINDENT
.sp
Mountpoints can also be configured on a \fI\%per\-remote basis\fP\&.
+.SS Using gitfs in Masterless Mode
+.sp
+Since 2014.7.0, gitfs can be used in masterless mode. To do so, simply add the
+gitfs configuration parameters (and set \fBfileserver_backend\fP) in
+the _minion_ config file instead of the master config file.
.SS Using gitfs Alongside Other Backends
.sp
Sometimes it may make sense to use multiple backends; for instance, if \fBsls\fP
files are stored in git but larger files are stored directly on the master.
.sp
-The cascading lookup logic used for multiple remotes is also used with
-multiple backends. If the \fBfileserver_backend\fP option contains
-multiple backends:
+The cascading lookup logic used for multiple remotes is also used with multiple
+backends. If the \fBfileserver_backend\fP option contains multiple
+backends:
.INDENT 0.0
.INDENT 3.5
.sp
@@ -21265,6 +21884,19 @@ my_repo:
.UNINDENT
.sp
For HTTP/HTTPS Basic authorization you can define credentials:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+my_repo:
+ url: https://spm.example.com/
+ username: user
+ password: pass
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
.sp
Beware of unauthorized access to this file, please set at least 0640 permissions for this configuration file:
.sp
@@ -21634,6 +22266,19 @@ states are evaluated before \fBtgt\fP states.
.sp
Each of these sections needs to be evaluated as text, rather than as YAML.
Consider the following block:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+pre_local_state: >
+ echo test > /tmp/spmtest:
+ cmd:
+ \- run
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
.sp
Note that this declaration uses \fB>\fP after \fBpre_local_state\fP\&. This is a YAML
marker that marks the next multi\-line block as text, including newlines. It is
@@ -21649,6 +22294,19 @@ a minion.
\fBlocal\fP states do not require any special arguments, but they must still use
the \fB>\fP marker to denote that the state is evaluated as text, not a data
structure.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+pre_local_state: >
+ echo test > /tmp/spmtest:
+ cmd:
+ \- run
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
.SS tgt States
.sp
\fBtgt\fP states are issued against a remote target. This is analogous to issuing
@@ -21657,6 +22315,21 @@ the \fBspm\fP command is running on is a master.
.sp
Because \fBtgt\fP states require that a target be specified, their code blocks
are a little different. Consider the following state:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+pre_tgt_state:
+ tgt: \(aq*\(aq
+ data: >
+ echo test > /tmp/spmtest:
+ cmd:
+ \- run
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
.sp
With \fBtgt\fP states, the state data is placed under a \fBdata\fP section, inside
the \fB*_tgt_state\fP code block. The target is of course specified as a \fBtgt\fP
@@ -21673,6 +22346,21 @@ engine, as it would be with a standard state run.
This means that you can use Jinja or any other supported renderer inside of
Salt. All formula variables are available to the renderer, so you can reference
\fBFORMULA\fP data inside your state if you need to:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+pre_tgt_state:
+ tgt: \(aq*\(aq
+ data: >
+ echo {{ name }} > /tmp/spmtest:
+ cmd:
+ \- run
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
.sp
You may also declare your own variables inside the \fBFORMULA\fP\&. If SPM doesn\(aqt
recognize them then it will ignore them, so there are no restrictions on
@@ -22690,6 +23378,9 @@ actual message that we are sending. With this flexible wire protocol we can
implement any message semantics that we\(aqd like\-\- including multiplexed message
passing on a single socket.
.SS TLS Support
+.sp
+New in version 2016.11.1.
+
.sp
The TCP transport allows for the master/minion communication to be optionally
wrapped in a TLS connection. Enabling this is simple, the master and minion need
@@ -23155,9 +23846,9 @@ def returner(ret):
\(aq\(aq\(aq
# Get a redis connection
serv = redis.Redis(
- host=\(aqredis\-serv.example.com\(aq,
- port=6379,
- db=\(aq0\(aq)
+ host=\(aqredis\-serv.example.com\(aq,
+ port=6379,
+ db=\(aq0\(aq)
serv.sadd("%(id)s:jobs" % ret, ret[\(aqjid\(aq])
serv.set("%(jid)s:%(id)s" % ret, json.dumps(ret[\(aqreturn\(aq]))
serv.sadd(\(aqjobs\(aq, ret[\(aqjid\(aq])
@@ -24734,6 +25425,11 @@ etcd.returner_write_profile: my_etcd_write
.UNINDENT
.INDENT 0.0
.TP
+.B salt.returners.etcd_return.__virtual__()
+Only return if python\-etcd is installed
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.returners.etcd_return.get_fun()
Return a dict of the last function called for all minions
.UNINDENT
@@ -24870,6 +25566,11 @@ values at the time of pillar generation, these will contain minion values at
the time of execution.
.INDENT 0.0
.TP
+.B salt.returners.highstate_return.__virtual__()
+Return our name
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.returners.highstate_return.returner(ret)
Check highstate return information and possibly fire off an email
or save a file.
@@ -25015,6 +25716,16 @@ salt \(aq*\(aq test.ping \-\-return hipchat \-\-return_kwargs \(aq{"room_id": "a
.UNINDENT
.INDENT 0.0
.TP
+.B salt.returners.hipchat_return.__virtual__()
+Return virtual name of the module.
+.INDENT 7.0
+.TP
+.B Returns
+The virtual name of the module.
+.UNINDENT
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.returners.hipchat_return.event_return(events)
Return event data to hipchat
.UNINDENT
@@ -25425,6 +26136,16 @@ salt \(aq*\(aq test.ping \-\-return mattermost \-\-return_kwargs \(aq{\(aqchanne
.UNINDENT
.INDENT 0.0
.TP
+.B salt.returners.mattermost_returner.__virtual__()
+Return virtual name of the module.
+.INDENT 7.0
+.TP
+.B Returns
+The virtual name of the module.
+.UNINDENT
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.returners.mattermost_returner.event_return(events)
Send the events to a mattermost room.
.INDENT 7.0
@@ -26224,6 +26945,11 @@ salt \(aq*\(aq test.ping \-\-return nagios \-\-return_kwargs \(aq{"service": "se
.UNINDENT
.INDENT 0.0
.TP
+.B salt.returners.nagios_return.__virtual__()
+Return virtualname
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.returners.nagios_return.returner(ret)
Send a message to Nagios with the data
.UNINDENT
@@ -27225,6 +27951,16 @@ salt \(aq*\(aq test.ping \-\-return pushover \-\-return_kwargs \(aq{"title": "Sa
.UNINDENT
.INDENT 0.0
.TP
+.B salt.returners.pushover_returner.__virtual__()
+Return virtual name of the module.
+.INDENT 7.0
+.TP
+.B Returns
+The virtual name of the module.
+.UNINDENT
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.returners.pushover_returner.returner(ret)
Send an PushOver message with the data
.UNINDENT
@@ -27569,6 +28305,16 @@ salt \(aq*\(aq test.ping \-\-return slack \-\-return_kwargs \(aq{"channel": "#ra
.UNINDENT
.INDENT 0.0
.TP
+.B salt.returners.slack_returner.__virtual__()
+Return virtual name of the module.
+.INDENT 7.0
+.TP
+.B Returns
+The virtual name of the module.
+.UNINDENT
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.returners.slack_returner.returner(ret)
Send an slack message with the data
.UNINDENT
@@ -27849,6 +28595,12 @@ Run a test by using \fBsalt\-call test.ping \-\-return splunk\fP
Written by Scott Pack (github.com/scottjpack)
.INDENT 0.0
.TP
+.B salt.returners.splunk.__virtual__()
+Return virtual name of the module.
+:return: The virtual name of the module.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.returners.splunk.returner(ret)
Send a message to Splunk via the HTTP Event Collector
.UNINDENT
@@ -28283,6 +29035,11 @@ salt \(aq*\(aq test.ping \-\-return xmpp \-\-return_kwargs \(aq{"recipient": "so
.UNINDENT
.INDENT 0.0
.TP
+.B salt.returners.xmpp_return.__virtual__()
+Only load this module if right version of sleekxmpp is installed on this minion.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.returners.xmpp_return.returner(ret)
Send an xmpp message with the data
.UNINDENT
@@ -29306,135 +30063,70 @@ A Python data structure
.UNINDENT
.UNINDENT
.SS salt.renderers.pass module
-.sp
-Pass Renderer for Salt
+.SS Pass Renderer for Salt
.sp
[pass](\fI\%https://www.passwordstore.org/\fP)
.sp
New in version 2017.7.0.
+.SS Setup
.sp
-# Setup
-__Note__: \fI\fP needs to be replaced with the user salt\-master will be
-running as
+\fBNOTE:\fP
+.INDENT 0.0
+.INDENT 3.5
+\fB\fP needs to be replaced with the user salt\-master will be running
+as
+.UNINDENT
+.UNINDENT
.INDENT 0.0
.IP 1. 3
-Have private gpg loaded into \fIuser\fP\(aqs gpg keyring
-* Example salt code
+Have private gpg loaded into \fIuser\fP\(aqs gpg keyring. Example:
.INDENT 3.0
.INDENT 3.5
-
+.sp
.nf
-\(ga\(ga
-.fi
-\(ga
+.ft C
load_private_gpg_key:
-.INDENT 0.0
-.INDENT 3.5
-.INDENT 0.0
-.TP
-.B cmd.run:
-.INDENT 7.0
-.IP \(bu 2
-name: gpg \-\-import
-.IP \(bu 2
-unless: gpg \-\-list\-keys \(aq\(aq
-.UNINDENT
-.UNINDENT
-.UNINDENT
-.UNINDENT
-.sp
-
-.nf
-\(ga\(ga
+ cmd.run:
+ \- name: gpg \-\-import
+ \- unless: gpg \-\-list\-keys \(aq\(aq
+.ft P
.fi
-
-.nf
-\(ga
-.fi
-
.UNINDENT
.UNINDENT
-.UNINDENT
-.sp
-1. Said private key\(aqs public key should have been used when encrypting pass
-entries that are of interest for pillar data
-1. Fetch and keep local pass git repo up\-to\-date
-.INDENT 0.0
-.INDENT 3.5
-.INDENT 0.0
-.IP \(bu 2
-.INDENT 2.0
-.TP
-.B Example salt code
-
-.nf
-\(ga\(ga
-.fi
-\(ga
-update_pass:
-.INDENT 7.0
-.INDENT 3.5
-.INDENT 0.0
-.TP
-.B git.latest:
-.INDENT 7.0
-.IP \(bu 2
-force_reset: True
-.IP \(bu 2
-name:
-.IP \(bu 2
-target: //.password\-store
-.IP \(bu 2
-identity:
-.IP \(bu 2
-require:
-\- cmd: load_private_gpg_key
-.UNINDENT
-.UNINDENT
-.UNINDENT
-.UNINDENT
-.sp
-
-.nf
-\(ga\(ga
-.fi
-
-.nf
-\(ga
-.fi
-
-.UNINDENT
-.UNINDENT
-.UNINDENT
-.UNINDENT
-.INDENT 0.0
-.IP 1. 3
-Install pass binary
-* Example salt code
+.IP 2. 3
+Said private key\(aqs public key should have been used when encrypting pass
+entries that are of interest for pillar data.
+.IP 3. 3
+Fetch and keep local pass git repo up\-to\-date
.INDENT 3.0
.INDENT 3.5
-
-.nf
-\(ga\(ga
-.fi
-\(ga
-pass:
-.INDENT 0.0
-.INDENT 3.5
-pkg.installed
-.UNINDENT
-.UNINDENT
.sp
-
.nf
-\(ga\(ga
+.ft C
+update_pass:
+ git.latest:
+ \- force_reset: True
+ \- name:
+ \- target: //.password\-store
+ \- identity:
+ \- require:
+ \- cmd: load_private_gpg_key
+.ft P
.fi
-
+.UNINDENT
+.UNINDENT
+.IP 4. 3
+Install pass binary
+.INDENT 3.0
+.INDENT 3.5
+.sp
.nf
-\(ga
+.ft C
+pass:
+ pkg.installed
+.ft P
.fi
-
.UNINDENT
.UNINDENT
.UNINDENT
@@ -29444,11 +30136,11 @@ pkg.installed
Fetch secret from pass based on pass_path
.UNINDENT
.SS salt.renderers.py
+.SS Pure python state renderer
.sp
-Pure python state renderer
+To use this renderer, the SLS file should contain a function called \fBrun\fP
+which returns highstate data.
.sp
-The SLS file should contain a function called \fBrun\fP which returns high state
-data.
The highstate data is a dictionary containing identifiers as keys, and execution
dictionaries as values. For example the following state declaration in YAML:
.INDENT 0.0
@@ -29497,7 +30189,8 @@ python SLS file. To use a different environment, the environment should be
set when executing the state. This can be done in a couple different ways:
.INDENT 2.0
.IP \(bu 2
-Using the \fBsaltenv\fP argument on the salt CLI (i.e. \fBsalt \(aq*\(aq state.sls foo.bar.baz saltenv=env_name\fP).
+Using the \fBsaltenv\fP argument on the salt CLI (i.e. \fBsalt \(aq*\(aq state.sls
+foo.bar.baz saltenv=env_name\fP).
.IP \(bu 2
By adding a \fBsaltenv\fP argument to an individual state within the SLS
file. In other words, adding a line like this to the state\(aqs data
@@ -29510,12 +30203,8 @@ environment is \fB/srv/salt\fP, and the SLS file is
\fBfoo.bar.baz\fP\&.
.UNINDENT
.sp
-The global contet \fIdata\fP (same as context
-.nf
-\(ga\(ga
-.fi
-{{ data }}\(ga \(ga for states written with Jinja + YAML.
-The following YAML + Jinja state declaration:
+The global context \fBdata\fP (same as context \fB{{ data }}\fP for states written
+with Jinja + YAML). The following YAML + Jinja state declaration:
.INDENT 0.0
.INDENT 3.5
.sp
@@ -29531,7 +30220,7 @@ highstate_run:
.UNINDENT
.UNINDENT
.sp
-Translate to:
+translates to:
.INDENT 0.0
.INDENT 3.5
.sp
@@ -29543,6 +30232,7 @@ if data[\(aqid\(aq] == \(aqmysql1\(aq:
.fi
.UNINDENT
.UNINDENT
+.SS Full Example
.INDENT 0.0
.INDENT 3.5
.sp
@@ -31147,8 +31837,8 @@ set.
The grains are derived by executing all of the "public" functions (i.e. those
which do not begin with an underscore) found in the modules located in the
Salt\(aqs core grains code, followed by those in any custom grains modules. The
-functions in a grains module must return a Python \fI\%dict\fP, where the dictionary keys are the names of grains, and
-each key\(aqs value is that value for that grain.
+functions in a grains module must return a \fI\%Python dictionary\fP, where the dictionary keys are the names of grains, and each
+key\(aqs value is that value for that grain.
.sp
Custom grains modules should be placed in a subdirectory named \fB_grains\fP
located under the \fBfile_roots\fP specified by the master config
@@ -31488,7 +32178,7 @@ targeting to them via a top file will have the key of \fBcompany\fP with a value
of \fBFoo Industries\fP\&.
.sp
Consequently this data can be used from within modules, renderers, State SLS
-files, and more via the shared pillar \fI\%dict\fP:
+files, and more via the shared pillar dictionary:
.INDENT 0.0
.INDENT 3.5
.sp
@@ -32813,6 +33503,18 @@ salt \(aq*\(aq state.sls my_sls_file pillar=\(aq{"foo": {"bar": "baz"}}\(aq
.UNINDENT
.UNINDENT
.sp
+Lists can be passed via command line pillar data as follows:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+salt \(aq*\(aq state.sls my_sls_file pillar=\(aq{"some_list": ["foo", "bar", "baz"]}\(aq
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
@@ -33038,7 +33740,7 @@ the minion was a new host.
.UNINDENT
.SS Globbing
.sp
-The default matching that Salt utilizes is \fI\%shell\-style globbing\fP around the minion id\&. This also works for states
+The default matching that Salt utilizes is \fBshell\-style globbing\fP around the minion id\&. This also works for states
in the top file\&.
.sp
\fBNOTE:\fP
@@ -33132,7 +33834,7 @@ compound matchers documentation.
.UNINDENT
.SS Regular Expressions
.sp
-Minions can be matched using Perl\-compatible \fI\%regular expressions\fP (which is globbing on steroids and a ton of caffeine).
+Minions can be matched using Perl\-compatible \fBregular expressions\fP (which is globbing on steroids and a ton of caffeine).
.sp
Match both \fBweb1\-prod\fP and \fBweb1\-devel\fP minions:
.INDENT 0.0
@@ -33205,11 +33907,10 @@ salt \-G \(aqcpuarch:x86_64\(aq grains.item num_cpus
.UNINDENT
.sp
Additionally, globs can be used in grain matches, and grains that are nested in
-a \fI\%dictionary\fP can be matched by adding a colon for
-each level that is traversed. For example, the following will match hosts that
-have a grain called \fBec2_tags\fP, which itself is a
-\fI\%dict\fP with a key named \fBenvironment\fP, which
-has a value that contains the word \fBproduction\fP:
+a dictionary can be matched by adding a colon for each level that is traversed.
+For example, the following will match hosts that have a grain called
+\fBec2_tags\fP, which itself is a dictionary with a key named \fBenvironment\fP,
+which has a value that contains the word \fBproduction\fP:
.INDENT 0.0
.INDENT 3.5
.sp
@@ -33317,7 +34018,7 @@ It is also possible to use in both pillar and state\-matching
.SS Compound matchers
.sp
Compound matchers allow very granular minion targeting using any of Salt\(aqs
-matchers. The default matcher is a \fI\%glob\fP match, just as
+matchers. The default matcher is a \fBglob\fP match, just as
with CLI and top file matching. To match using anything other than a
glob, prefix the match string with the appropriate letter from the table below,
followed by an \fB@\fP sign.
@@ -33421,7 +34122,7 @@ Matchers can be joined using boolean \fBand\fP, \fBor\fP, and \fBnot\fP operator
.sp
For example, the following string matches all Debian minions with a hostname
that begins with \fBwebserv\fP, as well as any minions that have a hostname which
-matches the \fI\%regular expression\fP \fBweb\-dc1\-srv.*\fP:
+matches the \fBregular expression\fP \fBweb\-dc1\-srv.*\fP:
.INDENT 0.0
.INDENT 3.5
.sp
@@ -34485,8 +35186,7 @@ Jinja statements and expressions are allowed by default in SLS files. See
Understanding Jinja\&.
.SS Understanding Jinja
.sp
-\fI\%Jinja\fP is the default templating language
-in SLS files.
+\fI\%Jinja\fP is the default templating language in SLS files.
.SS Jinja in States
.sp
Jinja is evaluated before YAML, which means it is evaluated before the States
@@ -34661,10 +35361,8 @@ starts at the root of the state tree or pillar.
Saltstack extends \fI\%builtin filters\fP with these custom filters:
.SS \fBstrftime\fP
.sp
-Converts any time related object into a time based string. It requires a
-valid \fI\%strftime directives\fP\&. An
-\fI\%exhaustive list\fP can be found in
-the official Python documentation.
+Converts any time related object into a time based string. It requires valid
+strftime directives. An exhaustive list can be found \fI\%here\fP in the Python documentation.
.INDENT 0.0
.INDENT 3.5
.sp
@@ -36521,11 +37219,7 @@ unique = [\(aqfoo\(aq, \(aqbar\(aq]
.UNINDENT
.SS Jinja in Files
.sp
-
-.nf
-Jinja_
-.fi
- can be used in the same way in managed files:
+\fI\%Jinja\fP can be used in the same way in managed files:
.INDENT 0.0
.INDENT 3.5
.sp
@@ -36803,2521 +37497,3721 @@ get the routes to \fB0.0.0.0/0\fP using the \fBNAPALM route\fP:
.UNINDENT
.UNINDENT
.SS Tutorials Index
-.INDENT 0.0
-.IP \(bu 2
-Salt as a Cloud Controller
-.IP \(bu 2
-Using Cron with Salt
-.IP \(bu 2
-Automatic Updates / Frozen Deployments
-.IP \(bu 2
-ESXi Proxy Minion
-.IP \(bu 2
-Opening the Firewall up for Salt
-.IP \(bu 2
-Git Fileserver Backend Walkthrough
-.IP \(bu 2
-Halite
-.IP \(bu 2
-HTTP Modules
-.IP \(bu 2
-Using Salt at Scale
-.IP \(bu 2
-LXC Management with Salt
-.IP \(bu 2
-MinionFS Backend Walkthrough
-.IP \(bu 2
-Remote Execution Tutorial
-.IP \(bu 2
-Multi\-Master\-PKI Tutorial With Failover
-.IP \(bu 2
-Multi Master Tutorial
-.IP \(bu 2
-Pillar Walkthrough
-.IP \(bu 2
-Packaging External Modules for Salt
-.IP \(bu 2
-Salt Masterless Quickstart
-.IP \(bu 2
-running salt as normal user tutorial
-.IP \(bu 2
-Salt Bootstrap
-.IP \(bu 2
-Standalone Minion
-.IP \(bu 2
-How Do I Use Salt States?
-.IP \(bu 2
-States tutorial, part 1 \- Basic Usage
-.IP \(bu 2
-States tutorial, part 2 \- More Complex States, Requisites
-.IP \(bu 2
-States tutorial, part 3 \- Templating, Includes, Extends
-.IP \(bu 2
-States tutorial, part 4
-.IP \(bu 2
-How to Convert Jinja Logic to an Execution Module
-.IP \(bu 2
-Using Salt with Stormpath
-.IP \(bu 2
-Syslog\-ng usage
-.IP \(bu 2
-The macOS (Maverick) Developer Step By Step Guide To Salt Installation
-.IP \(bu 2
-SaltStack Walk\-through
-.IP \(bu 2
-Writing Salt Tests
-.IP \(bu 2
-Running Salt States and Commands in Docker Containers
-.IP \(bu 2
-Preseed Minion with Accepted Key
-.UNINDENT
-.SS Troubleshooting
+.SS Salt as a Cloud Controller
.sp
-The intent of the troubleshooting section is to introduce solutions to a
-number of common issues encountered by users and the tools that are available
-to aid in developing States and Salt code.
-.SS Troubleshooting the Salt Master
+In Salt 0.14.0, an advanced cloud control system were introduced, allow
+private cloud vms to be managed directly with Salt. This system is generally
+referred to as \fBSalt Virt\fP\&.
.sp
-If your Salt master is having issues such as minions not returning data, slow
-execution times, or a variety of other issues, the following links contain
-details on troubleshooting the most common issues encountered:
-.SS Troubleshooting the Salt Master
-.SS Running in the Foreground
-.sp
-A great deal of information is available via the debug logging system, if you
-are having issues with minions connecting or not starting run the master in
-the foreground:
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-# salt\-master \-l debug
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-Anyone wanting to run Salt daemons via a process supervisor such as \fI\%monit\fP,
-\fI\%runit\fP, or \fI\%supervisord\fP, should omit the \fB\-d\fP argument to the daemons and
-run them in the foreground.
-.SS What Ports does the Master Need Open?
-.sp
-For the master, TCP ports 4505 and 4506 need to be open. If you\(aqve put both
-your Salt master and minion in debug mode and don\(aqt see an acknowledgment
-that your minion has connected, it could very well be a firewall interfering
-with the connection. See our firewall configuration page for help opening the firewall on various
-platforms.
-.sp
-If you\(aqve opened the correct TCP ports and still aren\(aqt seeing connections,
-check that no additional access control system such as \fI\%SELinux\fP or
-\fI\%AppArmor\fP is blocking Salt.
-.SS Too many open files
-.sp
-The salt\-master needs at least 2 sockets per host that connects to it, one for
-the Publisher and one for response port. Thus, large installations may, upon
-scaling up the number of minions accessing a given master, encounter:
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-12:45:29,289 [salt.master ][INFO ] Starting Salt worker process 38
-Too many open files
-sock != \-1 (tcp_listener.cpp:335)
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-The solution to this would be to check the number of files allowed to be
-opened by the user running salt\-master (root by default):
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-[root@salt\-master ~]# ulimit \-n
-1024
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-If this value is not equal to at least twice the number of minions, then it
-will need to be raised. For example, in an environment with 1800 minions, the
-\fBnofile\fP limit should be set to no less than 3600. This can be done by
-creating the file \fB/etc/security/limits.d/99\-salt.conf\fP, with the following
-contents:
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-root hard nofile 4096
-root soft nofile 4096
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-Replace \fBroot\fP with the user under which the master runs, if different.
-.sp
-If your master does not have an \fB/etc/security/limits.d\fP directory, the lines
-can simply be appended to \fB/etc/security/limits.conf\fP\&.
-.sp
-As with any change to resource limits, it is best to stay logged into your
-current shell and open another shell to run \fBulimit \-n\fP again and verify that
-the changes were applied correctly. Additionally, if your master is running
-upstart, it may be necessary to specify the \fBnofile\fP limit in
-\fB/etc/default/salt\-master\fP if upstart isn\(aqt respecting your resource limits:
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-limit nofile 4096 4096
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
+The Salt Virt system already exists and is installed within Salt itself, this
+means that besides setting up Salt, no additional salt code needs to be
+deployed.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
-The above is simply an example of how to set these values, and you may
-wish to increase them even further if your Salt master is doing more than
-just running Salt.
-.UNINDENT
-.UNINDENT
-.SS Salt Master Stops Responding
-.sp
-There are known bugs with ZeroMQ versions less than 2.1.11 which can cause the
-Salt master to not respond properly. If you\(aqre running a ZeroMQ version greater
-than or equal to 2.1.9, you can work around the bug by setting the sysctls
-\fBnet.core.rmem_max\fP and \fBnet.core.wmem_max\fP to 16777216. Next, set the third
-field in \fBnet.ipv4.tcp_rmem\fP and \fBnet.ipv4.tcp_wmem\fP to at least 16777216.
-.sp
-You can do it manually with something like:
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-# echo 16777216 > /proc/sys/net/core/rmem_max
-# echo 16777216 > /proc/sys/net/core/wmem_max
-# echo "4096 87380 16777216" > /proc/sys/net/ipv4/tcp_rmem
-# echo "4096 87380 16777216" > /proc/sys/net/ipv4/tcp_wmem
-.ft P
-.fi
+The \fBlibvirt\fP python module and the \fBcerttool\fP binary are required.
.UNINDENT
.UNINDENT
.sp
-Or with the following Salt state:
-.INDENT 0.0
-.INDENT 3.5
+The main goal of Salt Virt is to facilitate a very fast and simple cloud. The
+cloud that can scale and is fully featured. Salt Virt comes with the
+ability to set up and manage complex virtual machine networking, powerful
+image and disk management, as well as virtual machine migration with and without
+shared storage.
.sp
-.nf
-.ft C
-net.core.rmem_max:
- sysctl:
- \- present
- \- value: 16777216
-
-net.core.wmem_max:
- sysctl:
- \- present
- \- value: 16777216
-
-net.ipv4.tcp_rmem:
- sysctl:
- \- present
- \- value: 4096 87380 16777216
-
-net.ipv4.tcp_wmem:
- sysctl:
- \- present
- \- value: 4096 87380 16777216
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.SS Live Python Debug Output
+This means that Salt Virt can be used to create a cloud from a blade center
+and a SAN, but can also create a cloud out of a swarm of Linux Desktops
+without a single shared storage system. Salt Virt can make clouds from
+truly commodity hardware, but can also stand up the power of specialized
+hardware as well.
+.SS Setting up Hypervisors
.sp
-If the master seems to be unresponsive, a SIGUSR1 can be passed to the
-salt\-master threads to display what piece of code is executing. This debug
-information can be invaluable in tracking down bugs.
+The first step to set up the hypervisors involves getting the correct software
+installed and setting up the hypervisor network interfaces.
+.SS Installing Hypervisor Software
.sp
-To pass a SIGUSR1 to the master, first make sure the minion is running in the
-foreground. Stop the service if it is running as a daemon, and start it in the
-foreground like so:
-.INDENT 0.0
-.INDENT 3.5
+Salt Virt is made to be hypervisor agnostic but currently the only fully
+implemented hypervisor is KVM via libvirt.
.sp
-.nf
-.ft C
-# salt\-master \-l debug
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-Then pass the signal to the master when it seems to be unresponsive:
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-# killall \-SIGUSR1 salt\-master
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-When filing an issue or sending questions to the mailing list for a problem
-with an unresponsive daemon, be sure to include this information if possible.
-.SS Live Salt\-Master Profiling
-.sp
-When faced with performance problems one can turn on master process profiling by
-sending it SIGUSR2.
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-# killall \-SIGUSR2 salt\-master
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-This will activate \fByappi\fP profiler inside salt\-master code, then after some
-time one must send SIGUSR2 again to stop profiling and save results to file. If
-run in foreground salt\-master will report filename for the results, which are
-usually located under \fB/tmp\fP on Unix\-based OSes and \fBc:\etemp\fP on windows.
-.sp
-Results can then be analyzed with \fI\%kcachegrind\fP or similar tool.
-.SS Commands Time Out or Do Not Return Output
-.sp
-Depending on your OS (this is most common on Ubuntu due to apt\-get) you may
-sometimes encounter times where a \fBstate.apply\fP, or other long running commands do not return
-output.
-.sp
-By default the timeout is set to 5 seconds. The timeout value can easily be
-increased by modifying the \fBtimeout\fP line within your \fB/etc/salt/master\fP
-configuration file.
-.sp
-Having keys accepted for Salt minions that no longer exist or are not reachable
-also increases the possibility of timeouts, since the Salt master waits for
-those systems to return command results.
-.SS Passing the \-c Option to Salt Returns a Permissions Error
-.sp
-Using the \fB\-c\fP option with the Salt command modifies the configuration
-directory. When the configuration file is read it will still base data off of
-the \fBroot_dir\fP setting. This can result in unintended behavior if you are
-expecting files such as \fB/etc/salt/pki\fP to be pulled from the location
-specified with \fB\-c\fP\&. Modify the \fBroot_dir\fP setting to address this
-behavior.
-.SS Salt Master Doesn\(aqt Return Anything While Running jobs
-.sp
-When a command being run via Salt takes a very long time to return
-(package installations, certain scripts, etc.) the master may drop you back
-to the shell. In most situations the job is still running but Salt has
-exceeded the set timeout before returning. Querying the job queue will
-provide the data of the job but is inconvenient. This can be resolved by
-either manually using the \fB\-t\fP option to set a longer timeout when running
-commands (by default it is 5 seconds) or by modifying the master
-configuration file: \fB/etc/salt/master\fP and setting the \fBtimeout\fP value to
-change the default timeout for all commands, and then restarting the
-salt\-master service.
-.SS Salt Master Auth Flooding
-.sp
-In large installations, care must be taken not to overwhealm the master with
-authentication requests. Several options can be set on the master which
-mitigate the chances of an authentication flood from causing an interruption in
-service.
+The required software for a hypervisor is libvirt and kvm. For advanced
+features install libguestfs or qemu\-nbd.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
-recon_default:
-.sp
-The average number of seconds to wait between reconnection attempts.
-.INDENT 0.0
-.TP
-.B recon_max:
-The maximum number of seconds to wait between reconnection attempts.
-.TP
-.B recon_randomize:
-A flag to indicate whether the recon_default value should be randomized.
-.TP
-.B acceptance_wait_time:
-The number of seconds to wait for a reply to each authentication request.
-.TP
-.B random_reauth_delay:
-The range of seconds across which the minions should attempt to randomize
-authentication attempts.
-.TP
-.B auth_timeout:
-The total time to wait for the authentication process to complete, regardless
-of the number of attempts.
-.UNINDENT
-.UNINDENT
-.UNINDENT
-.SS Running states locally
-.sp
-To debug the states, you can use call locally.
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-salt\-call \-l trace \-\-local state.highstate
-.ft P
-.fi
+Libguestfs and qemu\-nbd allow for virtual machine images to be mounted
+before startup and get pre\-seeded with configurations and a salt minion
.UNINDENT
.UNINDENT
.sp
-The top.sls file is used to map what SLS modules get loaded onto what minions via the state system.
-.sp
-It is located in the file defined in the \fBfile_roots\fP variable of the salt master
-configuration file which is defined by found in \fBCONFIG_DIR/master\fP, normally \fB/etc/salt/master\fP
-.sp
-The default configuration for the \fBfile_roots\fP is:
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-file_roots:
- base:
- \- /srv/salt
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-So the top file is defaulted to the location \fB/srv/salt/top.sls\fP
-.SS Salt Master Umask
-.sp
-The salt master uses a cache to track jobs as they are published and returns come back.
-The recommended umask for a salt\-master is \fI022\fP, which is the default for most users
-on a system. Incorrect umasks can result in permission\-denied errors when the master
-tries to access files in its cache.
-.SS Troubleshooting the Salt Minion
-.sp
-In the event that your Salt minion is having issues, a variety of solutions
-and suggestions are available. Please refer to the following links for more information:
-.SS Troubleshooting the Salt Minion
-.SS Running in the Foreground
-.sp
-A great deal of information is available via the debug logging system, if you
-are having issues with minions connecting or not starting run the minion in
-the foreground:
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-# salt\-minion \-l debug
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-Anyone wanting to run Salt daemons via a process supervisor such as \fI\%monit\fP,
-\fI\%runit\fP, or \fI\%supervisord\fP, should omit the \fB\-d\fP argument to the daemons and
-run them in the foreground.
-.SS What Ports does the Minion Need Open?
-.sp
-No ports need to be opened on the minion, as it makes outbound connections to
-the master. If you\(aqve put both your Salt master and minion in debug mode and
-don\(aqt see an acknowledgment that your minion has connected, it could very well
-be a firewall interfering with the connection. See our firewall
-configuration page for help opening the firewall
-on various platforms.
-.sp
-If you have netcat installed, you can check port connectivity from the minion
-with the \fBnc\fP command:
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-$ nc \-v \-z salt.master.ip.addr 4505
-Connection to salt.master.ip.addr 4505 port [tcp/unknown] succeeded!
-$ nc \-v \-z salt.master.ip.addr 4506
-Connection to salt.master.ip.addr 4506 port [tcp/unknown] succeeded!
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-The \fI\%Nmap\fP utility can also be used to check if these ports are open:
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-# nmap \-sS \-q \-p 4505\-4506 salt.master.ip.addr
-
-Starting Nmap 6.40 ( http://nmap.org ) at 2013\-12\-29 19:44 CST
-Nmap scan report for salt.master.ip.addr (10.0.0.10)
-Host is up (0.0026s latency).
-PORT STATE SERVICE
-4505/tcp open unknown
-4506/tcp open unknown
-MAC Address: 00:11:22:AA:BB:CC (Intel)
-
-Nmap done: 1 IP address (1 host up) scanned in 1.64 seconds
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-If you\(aqve opened the correct TCP ports and still aren\(aqt seeing connections,
-check that no additional access control system such as \fI\%SELinux\fP or
-\fI\%AppArmor\fP is blocking Salt. Tools like \fI\%tcptraceroute\fP can also be used
-to determine if an intermediate device or firewall is blocking the needed
-TCP ports.
-.SS Using salt\-call
-.sp
-The \fBsalt\-call\fP command was originally developed for aiding in the
-development of new Salt modules. Since then, many applications have been
-developed for running any Salt module locally on a minion. These range from the
-original intent of salt\-call (development assistance), to gathering more
-verbose output from calls like \fBstate.apply\fP\&.
-.sp
-When initially creating your state tree, it is generally recommended to invoke
-highstates by running \fBstate.apply\fP directly
-from the minion with \fBsalt\-call\fP, rather than remotely from the master. This
-displays far more information about the execution than calling it remotely. For
-even more verbosity, increase the loglevel using the \fB\-l\fP argument:
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-# salt\-call \-l debug state.apply
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-The main difference between using \fBsalt\fP and using \fBsalt\-call\fP is that
-\fBsalt\-call\fP is run from the minion, and it only runs the selected function on
-that minion. By contrast, \fBsalt\fP is run from the master, and requires you to
-specify the minions on which to run the command using salt\(aqs targeting
-system\&.
-.SS Live Python Debug Output
-.sp
-If the minion seems to be unresponsive, a SIGUSR1 can be passed to the process
-to display what piece of code is executing. This debug information can be
-invaluable in tracking down bugs.
-.sp
-To pass a SIGUSR1 to the minion, first make sure the minion is running in the
-foreground. Stop the service if it is running as a daemon, and start it in the
-foreground like so:
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-# salt\-minion \-l debug
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-Then pass the signal to the minion when it seems to be unresponsive:
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-# killall \-SIGUSR1 salt\-minion
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-When filing an issue or sending questions to the mailing list for a problem
-with an unresponsive daemon, be sure to include this information if possible.
-.SS Multiprocessing in Execution Modules
-.sp
-As is outlined in github issue #6300, Salt cannot use python\(aqs multiprocessing
-pipes and queues from execution modules. Multiprocessing from the execution
-modules is perfectly viable, it is just necessary to use Salt\(aqs event system
-to communicate back with the process.
-.sp
-The reason for this difficulty is that python attempts to pickle all objects in
-memory when communicating, and it cannot pickle function objects. Since the
-Salt loader system creates and manages function objects this causes the pickle
-operation to fail.
-.SS Salt Minion Doesn\(aqt Return Anything While Running Jobs Locally
-.sp
-When a command being run via Salt takes a very long time to return
-(package installations, certain scripts, etc.) the minion may drop you back
-to the shell. In most situations the job is still running but Salt has
-exceeded the set timeout before returning. Querying the job queue will
-provide the data of the job but is inconvenient. This can be resolved by
-either manually using the \fB\-t\fP option to set a longer timeout when running
-commands (by default it is 5 seconds) or by modifying the minion
-configuration file: \fB/etc/salt/minion\fP and setting the \fBtimeout\fP value to
-change the default timeout for all commands, and then restarting the
-salt\-minion service.
+This sls will set up the needed software for a hypervisor, and run the routines
+to set up the libvirt pki keys.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
-Modifying the minion timeout value is not required when running commands
-from a Salt Master. It is only required when running commands locally on
-the minion.
+Package names and setup used is Red Hat specific, different package names
+will be required for different platforms
.UNINDENT
.UNINDENT
-.SS Running in the Foreground
-.sp
-A great deal of information is available via the debug logging system, if you
-are having issues with minions connecting or not starting run the minion and/or
-master in the foreground:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
-salt\-master \-l debug
-salt\-minion \-l debug
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-Anyone wanting to run Salt daemons via a process supervisor such as \fI\%monit\fP,
-\fI\%runit\fP, or \fI\%supervisord\fP, should omit the \fB\-d\fP argument to the daemons and
-run them in the foreground.
-.SS What Ports do the Master and Minion Need Open?
-.sp
-No ports need to be opened up on each minion. For the master, TCP ports 4505
-and 4506 need to be open. If you\(aqve put both your Salt master and minion in
-debug mode and don\(aqt see an acknowledgment that your minion has connected,
-it could very well be a firewall.
-.sp
-You can check port connectivity from the minion with the nc command:
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-nc \-v \-z salt.master.ip 4505
-nc \-v \-z salt.master.ip 4506
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-There is also a firewall configuration
-document that might help as well.
-.sp
-If you\(aqve enabled the right TCP ports on your operating system or Linux
-distribution\(aqs firewall and still aren\(aqt seeing connections, check that no
-additional access control system such as \fI\%SELinux\fP or \fI\%AppArmor\fP is blocking
-Salt.
-.SS Using salt\-call
-.sp
-The \fBsalt\-call\fP command was originally developed for aiding in the development
-of new Salt modules. Since then, many applications have been developed for
-running any Salt module locally on a minion. These range from the original
-intent of salt\-call, development assistance, to gathering more verbose output
-from calls like \fBstate.apply\fP\&.
-.sp
-When initially creating your state tree, it is generally recommended to invoke
-\fBstate.apply\fP directly from the minion with
-\fBsalt\-call\fP, rather than remotely from the master. This displays far more
-information about the execution than calling it remotely. For even more
-verbosity, increase the loglevel using the \fB\-l\fP argument:
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-salt\-call \-l debug state.apply
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-The main difference between using \fBsalt\fP and using \fBsalt\-call\fP is that
-\fBsalt\-call\fP is run from the minion, and it only runs the selected function on
-that minion. By contrast, \fBsalt\fP is run from the master, and requires you to
-specify the minions on which to run the command using salt\(aqs targeting
-system\&.
-.SS Too many open files
-.sp
-The salt\-master needs at least 2 sockets per host that connects to it, one for
-the Publisher and one for response port. Thus, large installations may, upon
-scaling up the number of minions accessing a given master, encounter:
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-12:45:29,289 [salt.master ][INFO ] Starting Salt worker process 38
-Too many open files
-sock != \-1 (tcp_listener.cpp:335)
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-The solution to this would be to check the number of files allowed to be
-opened by the user running salt\-master (root by default):
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-[root@salt\-master ~]# ulimit \-n
-1024
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-And modify that value to be at least equal to the number of minions x 2.
-This setting can be changed in limits.conf as the nofile value(s),
-and activated upon new a login of the specified user.
-.sp
-So, an environment with 1800 minions, would need 1800 x 2 = 3600 as a minimum.
-.SS Salt Master Stops Responding
-.sp
-There are known bugs with ZeroMQ versions less than 2.1.11 which can cause the
-Salt master to not respond properly. If you\(aqre running a ZeroMQ version greater
-than or equal to 2.1.9, you can work around the bug by setting the sysctls
-\fBnet.core.rmem_max\fP and \fBnet.core.wmem_max\fP to 16777216. Next, set the third
-field in \fBnet.ipv4.tcp_rmem\fP and \fBnet.ipv4.tcp_wmem\fP to at least 16777216.
-.sp
-You can do it manually with something like:
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-# echo 16777216 > /proc/sys/net/core/rmem_max
-# echo 16777216 > /proc/sys/net/core/wmem_max
-# echo "4096 87380 16777216" > /proc/sys/net/ipv4/tcp_rmem
-# echo "4096 87380 16777216" > /proc/sys/net/ipv4/tcp_wmem
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-Or with the following Salt state:
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-net.core.rmem_max:
- sysctl:
- \- present
- \- value: 16777216
-
-net.core.wmem_max:
- sysctl:
- \- present
- \- value: 16777216
-
-net.ipv4.tcp_rmem:
- sysctl:
- \- present
- \- value: 4096 87380 16777216
-
-net.ipv4.tcp_wmem:
- sysctl:
- \- present
- \- value: 4096 87380 16777216
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.SS Salt and SELinux
-.sp
-Currently there are no SELinux policies for Salt. For the most part Salt runs
-without issue when SELinux is running in Enforcing mode. This is because when
-the minion executes as a daemon the type context is changed to \fBinitrc_t\fP\&.
-The problem with SELinux arises when using salt\-call or running the minion in
-the foreground, since the type context stays \fBunconfined_t\fP\&.
-.sp
-This problem is generally manifest in the rpm install scripts when using the
-pkg module. Until a full SELinux Policy is available for Salt the solution
-to this issue is to set the execution context of \fBsalt\-call\fP and
-\fBsalt\-minion\fP to rpm_exec_t:
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-# CentOS 5 and RHEL 5:
-chcon \-t system_u:system_r:rpm_exec_t:s0 /usr/bin/salt\-minion
-chcon \-t system_u:system_r:rpm_exec_t:s0 /usr/bin/salt\-call
-
-# CentOS 6 and RHEL 6:
-chcon system_u:object_r:rpm_exec_t:s0 /usr/bin/salt\-minion
-chcon system_u:object_r:rpm_exec_t:s0 /usr/bin/salt\-call
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-This works well, because the \fBrpm_exec_t\fP context has very broad control over
-other types.
-.SS Red Hat Enterprise Linux 5
-.sp
-Salt requires Python 2.6 or 2.7. Red Hat Enterprise Linux 5 and its variants
-come with Python 2.4 installed by default. When installing on RHEL 5 from the
-\fI\%EPEL repository\fP this is handled for you. But, if you run Salt from git, be
-advised that its dependencies need to be installed from EPEL and that Salt
-needs to be run with the \fBpython26\fP executable.
-.SS Common YAML Gotchas
-.sp
-An extensive list of YAML idiosyncrasies has been compiled:
-.SS YAML Idiosyncrasies
-.sp
-One of Salt\(aqs strengths, the use of existing serialization systems for
-representing SLS data, can also backfire. \fI\%YAML\fP is a general purpose system
-and there are a number of things that would seem to make sense in an sls
-file that cause YAML issues. It is wise to be aware of these issues. While
-reports or running into them are generally rare they can still crop up at
-unexpected times.
-.SS Spaces vs Tabs
-.sp
-\fI\%YAML uses spaces\fP, period. Do not use tabs in your SLS files! If strange
-errors are coming up in rendering SLS files, make sure to check that
-no tabs have crept in! In Vim, after enabling search highlighting
-with: \fB:set hlsearch\fP, you can check with the following key sequence in
-normal mode(you can hit \fIESC\fP twice to be sure): \fB/\fP, \fICtrl\-v\fP, \fITab\fP, then
-hit \fIEnter\fP\&. Also, you can convert tabs to 2 spaces by these commands in Vim:
-\fB:set tabstop=2 expandtab\fP and then \fB:retab\fP\&.
-.SS Indentation
-.sp
-The suggested syntax for YAML files is to use 2 spaces for indentation,
-but YAML will follow whatever indentation system that the individual file
-uses. Indentation of two spaces works very well for SLS files given the
-fact that the data is uniform and not deeply nested.
-.SS Nested Dictionaries
-.sp
-When \fI\%dicts\fP are nested within other data
-structures (particularly lists), the indentation logic sometimes changes.
-Examples of where this might happen include \fBcontext\fP and \fBdefault\fP options
-from the \fBfile.managed\fP state:
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-/etc/http/conf/http.conf:
- file:
- \- managed
- \- source: salt://apache/http.conf
- \- user: root
- \- group: root
- \- mode: 644
- \- template: jinja
- \- context:
- custom_var: "override"
- \- defaults:
- custom_var: "default value"
- other_var: 123
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-Notice that while the indentation is two spaces per level, for the values under
-the \fBcontext\fP and \fBdefaults\fP options there is a four\-space indent. If only
-two spaces are used to indent, then those keys will be considered part of the
-same dictionary that contains the \fBcontext\fP key, and so the data will not be
-loaded correctly. If using a double indent is not desirable, then a
-deeply\-nested dict can be declared with curly braces:
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-/etc/http/conf/http.conf:
- file:
- \- managed
- \- source: salt://apache/http.conf
- \- user: root
- \- group: root
- \- mode: 644
- \- template: jinja
- \- context: {
- custom_var: "override" }
- \- defaults: {
- custom_var: "default value",
- other_var: 123 }
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-Here is a more concrete example of how YAML actually handles these
-indentations, using the Python interpreter on the command line:
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
->>> import yaml
->>> yaml.safe_load(\(aq\(aq\(aqmystate:
-\&... file.managed:
-\&... \- context:
-\&... some: var\(aq\(aq\(aq)
-{\(aqmystate\(aq: {\(aqfile.managed\(aq: [{\(aqcontext\(aq: {\(aqsome\(aq: \(aqvar\(aq}}]}}
->>> yaml.safe_load(\(aq\(aq\(aqmystate:
-\&... file.managed:
-\&... \- context:
-\&... some: var\(aq\(aq\(aq)
-{\(aqmystate\(aq: {\(aqfile.managed\(aq: [{\(aqsome\(aq: \(aqvar\(aq, \(aqcontext\(aq: None}]}}
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-Note that in the second example, \fBsome\fP is added as another key in the same
-dictionary, whereas in the first example, it\(aqs the start of a new dictionary.
-That\(aqs the distinction. \fBcontext\fP is a common example because it is a keyword
-arg for many functions, and should contain a dictionary.
-.SS True/False, Yes/No, On/Off
-.sp
-PyYAML will load these values as boolean \fBTrue\fP or \fBFalse\fP\&. Un\-capitalized
-versions will also be loaded as booleans (\fBtrue\fP, \fBfalse\fP, \fByes\fP, \fBno\fP,
-\fBon\fP, and \fBoff\fP). This can be especially problematic when constructing
-Pillar data. Make sure that your Pillars which need to use the string versions
-of these values are enclosed in quotes. Pillars will be parsed twice by salt,
-so you\(aqll need to wrap your values in multiple quotes, including double quotation
-marks (\fB" "\fP) and single quotation marks (\fB\(aq \(aq\fP). Note that spaces are included
-in the quotation type examples for clarity.
-.sp
-Multiple quoting examples looks like this:
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-\- \(aq"false"\(aq
-\- "\(aqTrue\(aq"
-\- "\(aqYES\(aq"
-\- \(aq"No"\(aq
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-\fBNOTE:\fP
-.INDENT 0.0
-.INDENT 3.5
-When using multiple quotes in this manner, they must be different. Using \fB"" ""\fP
-or \fB\(aq\(aq \(aq\(aq\fP won\(aqt work in this case (spaces are included in examples for clarity).
-.UNINDENT
-.UNINDENT
-.SS The \(aq%\(aq Sign
-.sp
-The \fI%\fP symbol has a special meaning in YAML, it needs to be passed as a
-string literal:
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-cheese:
- ssh_auth.present:
- \- user: tbortels
- \- source: salt://ssh_keys/chease.pub
- \- config: \(aq%h/.ssh/authorized_keys\(aq
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.SS Time Expressions
-.sp
-PyYAML will load a time expression as the integer value of that, assuming
-\fBHH:MM\fP\&. So for example, \fB12:00\fP is loaded by PyYAML as \fB720\fP\&. An
-excellent explanation for why can be found \fI\%here\fP\&.
-.sp
-To keep time expressions like this from being loaded as integers, always quote
-them.
-.sp
-\fBNOTE:\fP
-.INDENT 0.0
-.INDENT 3.5
-When using a jinja \fBload_yaml\fP map, items must be quoted twice. For
-example:
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-{% load_yaml as wsus_schedule %}
-
-FRI_10:
- time: \(aq"23:00"\(aq
- day: 6 \- Every Friday
-SAT_10:
- time: \(aq"06:00"\(aq
- day: 7 \- Every Saturday
-SAT_20:
- time: \(aq"14:00"\(aq
- day: 7 \- Every Saturday
-SAT_30:
- time: \(aq"22:00"\(aq
- day: 7 \- Every Saturday
-SUN_10:
- time: \(aq"06:00"\(aq
- day: 1 \- Every Sunday
-{% endload %}
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.UNINDENT
-.UNINDENT
-.SS YAML does not like "Double Short Decs"
-.sp
-If I can find a way to make YAML accept "Double Short Decs" then I will, since
-I think that double short decs would be awesome. So what is a "Double Short
-Dec"? It is when you declare a multiple short decs in one ID. Here is a
-standard short dec, it works great:
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-vim:
- pkg.installed
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-The short dec means that there are no arguments to pass, so it is not required
-to add any arguments, and it can save space.
-.sp
-YAML though, gets upset when declaring multiple short decs, for the record...
-.sp
-THIS DOES NOT WORK:
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-vim:
- pkg.installed
- user.present
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-Similarly declaring a short dec in the same ID dec as a standard dec does not
-work either...
-.sp
-ALSO DOES NOT WORK:
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-fred:
- user.present
- ssh_auth.present:
- \- name: AAAAB3NzaC...
- \- user: fred
- \- enc: ssh\-dss
- \- require:
- \- user: fred
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-The correct way is to define them like this:
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-vim:
+libvirt:
pkg.installed: []
- user.present: []
-
-fred:
- user.present: []
- ssh_auth.present:
- \- name: AAAAB3NzaC...
- \- user: fred
- \- enc: ssh\-dss
+ file.managed:
+ \- name: /etc/sysconfig/libvirtd
+ \- contents: \(aqLIBVIRTD_ARGS="\-\-listen"\(aq
\- require:
- \- user: fred
+ \- pkg: libvirt
+ virt.keys:
+ \- require:
+ \- pkg: libvirt
+ service.running:
+ \- name: libvirtd
+ \- require:
+ \- pkg: libvirt
+ \- network: br0
+ \- libvirt: libvirt
+ \- watch:
+ \- file: libvirt
+
+libvirt\-python:
+ pkg.installed: []
+
+libguestfs:
+ pkg.installed:
+ \- pkgs:
+ \- libguestfs
+ \- libguestfs\-tools
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.SS Hypervisor Network Setup
+.sp
+The hypervisors will need to be running a network bridge to serve up network
+devices for virtual machines, this formula will set up a standard bridge on
+a hypervisor connecting the bridge to eth0:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+eth0:
+ network.managed:
+ \- enabled: True
+ \- type: eth
+ \- bridge: br0
+
+br0:
+ network.managed:
+ \- enabled: True
+ \- type: bridge
+ \- proto: dhcp
+ \- require:
+ \- network: eth0
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.SS Virtual Machine Network Setup
+.sp
+Salt Virt comes with a system to model the network interfaces used by the
+deployed virtual machines; by default a single interface is created for the
+deployed virtual machine and is bridged to \fBbr0\fP\&. To get going with the
+default networking setup, ensure that the bridge interface named \fBbr0\fP exists
+on the hypervisor and is bridged to an active network device.
+.sp
+\fBNOTE:\fP
+.INDENT 0.0
+.INDENT 3.5
+To use more advanced networking in Salt Virt, read the \fISalt Virt
+Networking\fP document:
+.sp
+Salt Virt Networking
+.UNINDENT
+.UNINDENT
+.SS Libvirt State
+.sp
+One of the challenges of deploying a libvirt based cloud is the distribution
+of libvirt certificates. These certificates allow for virtual machine
+migration. Salt comes with a system used to auto deploy these certificates.
+Salt manages the signing authority key and generates keys for libvirt clients
+on the master, signs them with the certificate authority and uses pillar to
+distribute them. This is managed via the \fBlibvirt\fP state. Simply execute this
+formula on the minion to ensure that the certificate is in place and up to
+date:
+.sp
+\fBNOTE:\fP
+.INDENT 0.0
+.INDENT 3.5
+The above formula includes the calls needed to set up libvirt keys.
+.UNINDENT
+.UNINDENT
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+libvirt_keys:
+ virt.keys
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.SS Getting Virtual Machine Images Ready
+.sp
+Salt Virt, requires that virtual machine images be provided as these are not
+generated on the fly. Generating these virtual machine images differs greatly
+based on the underlying platform.
+.sp
+Virtual machine images can be manually created using KVM and running through
+the installer, but this process is not recommended since it is very manual and
+prone to errors.
+.sp
+Virtual Machine generation applications are available for many platforms:
+.INDENT 0.0
+.TP
+.B kiwi: (openSUSE, SLES, RHEL, CentOS)
+\fI\%https://suse.github.io/kiwi/\fP
+.TP
+.B vm\-builder:
+\fI\%https://wiki.debian.org/VMBuilder\fP
+.sp
+\fBSEE ALSO:\fP
+.INDENT 7.0
+.INDENT 3.5
+\fI\%vmbuilder\-formula\fP
+.UNINDENT
+.UNINDENT
+.UNINDENT
+.sp
+Once virtual machine images are available, the easiest way to make them
+available to Salt Virt is to place them in the Salt file server. Just copy an
+image into \fB/srv/salt\fP and it can now be used by Salt Virt.
+.sp
+For purposes of this demo, the file name \fBcentos.img\fP will be used.
+.SS Existing Virtual Machine Images
+.sp
+Many existing Linux distributions distribute virtual machine images which
+can be used with Salt Virt. Please be advised that NONE OF THESE IMAGES ARE
+SUPPORTED BY SALTSTACK.
+.SS CentOS
+.sp
+These images have been prepared for OpenNebula but should work without issue with
+Salt Virt, only the raw qcow image file is needed:
+\fI\%http://wiki.centos.org/Cloud/OpenNebula\fP
+.SS Fedora Linux
+.sp
+Images for Fedora Linux can be found here:
+\fI\%http://fedoraproject.org/en/get\-fedora#clouds\fP
+.SS openSUSE
+.sp
+\fI\%http://download.opensuse.org/repositories/openSUSE:/Leap:/42.1:/Images/images\fP
+.sp
+(look for JeOS\-for\-kvm\-and\-xen variant)
+.SS SUSE
+.sp
+\fI\%https://www.suse.com/products/server/jeos\fP
+.SS Ubuntu Linux
+.sp
+Images for Ubuntu Linux can be found here:
+\fI\%http://cloud\-images.ubuntu.com/\fP
+.SS Using Salt Virt
+.sp
+With hypervisors set up and virtual machine images ready, Salt can start
+issuing cloud commands using the \fIvirt runner\fP\&.
+.sp
+Start by running a Salt Virt hypervisor info command:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+salt\-run virt.host_info
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
-Alternatively, they can be defined the "old way", or with multiple
-"full decs":
+This will query the running hypervisor(s) for stats and display useful
+information such as the number of cpus and amount of memory.
+.sp
+You can also list all VMs and their current states on all hypervisor
+nodes:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+salt\-run virt.list
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Now that hypervisors are available a virtual machine can be provisioned.
+The \fBvirt.init\fP routine will create a new virtual machine:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+salt\-run virt.init centos1 2 512 salt://centos.img
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+The Salt Virt runner will now automatically select a hypervisor to deploy
+the new virtual machine on. Using \fBsalt://\fP assumes that the CentOS virtual
+machine image is located in the root of the file\-server on the master.
+When images are cloned (i.e. copied locatlly after retrieval from the file server)
+the destination directory on the hypervisor minion is determined by the \fBvirt.images\fP
+config option; by default this is \fB/srv/salt/salt\-images/\fP\&.
+.sp
+When a VM is initialized using \fBvirt.init\fP the image is copied to the hypervisor
+using \fBcp.cache_file\fP and will be mounted and seeded with a minion. Seeding includes
+setting pre\-authenticated keys on the new machine. A minion will only be installed if
+one can not be found on the image using the default arguments to \fBseed.apply\fP\&.
+.sp
+\fBNOTE:\fP
+.INDENT 0.0
+.INDENT 3.5
+The biggest bottleneck in starting VMs is when the Salt Minion needs to be
+installed. Making sure that the source VM images already have Salt
+installed will GREATLY speed up virtual machine deployment.
+.UNINDENT
+.UNINDENT
+.sp
+You can also deploy an image on a particular minion by directly calling the
+\fIvirt\fP execution module with an absolute image path. This can be quite handy for testing:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+salt \(aqhypervisor*\(aq virt.init centos1 2 512 image=/var/lib/libvirt/images/centos.img
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Now that the new VM has been prepared, it can be seen via the \fBvirt.query\fP
+command:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+salt\-run virt.query
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+This command will return data about all of the hypervisors and respective
+virtual machines.
+.sp
+Now that the new VM is booted it should have contacted the Salt Master, a
+\fBtest.ping\fP will reveal if the new VM is running.
+.SS QEMU copy on write support
+.sp
+For fast image cloning you can use the \fI\%qcow\fP disk image format.
+Pass the \fBenable_qcow\fP flag and a \fI\&.qcow2\fP image path to \fIvirt.init\fP:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+salt \(aqhypervisor*\(aq virt.init centos1 2 512 image=/var/lib/libvirt/images/centos.qcow2 enable_qcow=True start=False
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+\fBNOTE:\fP
+.INDENT 0.0
+.INDENT 3.5
+Beware that attempting to boot a qcow image too quickly after cloning
+can result in a race condition where libvirt may try to boot the machine
+before image seeding has completed. For that reason it is recommended to
+also pass \fBstart=False\fP to \fBvirt.init\fP\&.
+.sp
+Also know that you \fBmust not\fP modify the original base image without
+first making a copy and then \fIrebasing\fP all overlay images onto it.
+See the \fBqemu\-img rebase\fP \fI\%usage docs\fP\&.
+.UNINDENT
+.UNINDENT
+.SS Migrating Virtual Machines
+.sp
+Salt Virt comes with full support for virtual machine migration, and using
+the libvirt state in the above formula makes migration possible.
+.sp
+A few things need to be available to support migration. Many operating systems
+turn on firewalls when originally set up, the firewall needs to be opened up
+to allow for libvirt and kvm to cross communicate and execution migration
+routines. On Red Hat based hypervisors in particular port 16514 needs to be
+opened on hypervisors:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+iptables \-A INPUT \-m state \-\-state NEW \-m tcp \-p tcp \-\-dport 16514 \-j ACCEPT
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+\fBNOTE:\fP
+.INDENT 0.0
+.INDENT 3.5
+More in\-depth information regarding distribution specific firewall settings can read in:
+.sp
+Opening the Firewall up for Salt
+.UNINDENT
+.UNINDENT
+.sp
+Salt also needs the \fBvirt.tunnel\fP option to be turned on.
+This flag tells Salt to run migrations securely via the libvirt TLS tunnel and to
+use port 16514. Without \fBvirt.tunnel\fP libvirt tries to bind to random ports when
+running migrations.
+.sp
+To turn on \fBvirt.tunnel\fP simple apply it to the master config file:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+virt.tunnel: True
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Once the master config has been updated, restart the master and send out a call
+to the minions to refresh the pillar to pick up on the change:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+salt \e* saltutil.refresh_modules
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Now, migration routines can be run! To migrate a VM, simply run the Salt Virt
+migrate routine:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+salt\-run virt.migrate centos
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.SS VNC Consoles
+.sp
+Although not enabled by default, Salt Virt can also set up VNC consoles allowing for remote visual
+consoles to be opened up. When creating a new VM using \fBvirt.init\fP pass the \fBenable_vnc=True\fP
+parameter to have a console configured for the new VM.
+.sp
+The information from a \fBvirt.query\fP routine will display the vnc console port for the specific vms:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+centos
+ CPU: 2
+ Memory: 524288
+ State: running
+ Graphics: vnc \- hyper6:5900
+ Disk \- vda:
+ Size: 2.0G
+ File: /srv/salt\-images/ubuntu2/system.qcow2
+ File Format: qcow2
+ Nic \- ac:de:48:98:08:77:
+ Source: br0
+ Type: bridge
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+The line \fIGraphics: vnc \- hyper6:5900\fP holds the key. First the port named,
+in this case 5900, will need to be available in the hypervisor\(aqs firewall.
+Once the port is open, then the console can be easily opened via vncviewer:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+vncviewer hyper6:5900
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+By default there is no VNC security set up on these ports, which suggests that
+keeping them firewalled and mandating that SSH tunnels be used to access these
+VNC interfaces. Keep in mind that activity on a VNC interface that is accessed
+can be viewed by any other user that accesses that same VNC interface, and any other
+user logging in can also operate with the logged in user on the virtual
+machine.
+.SS Conclusion
+.sp
+Now with Salt Virt running, new hypervisors can be seamlessly added just by
+running the above states on new bare metal machines, and these machines will be
+instantly available to Salt Virt.
+.SS Running Salt States and Commands in Docker Containers
+.sp
+The 2016.11.0 release of Salt introduces the ability to execute Salt States
+and Salt remote execution commands directly inside of Docker containers.
+.sp
+This addition makes it possible to not only deploy fresh containers using
+Salt States. This also allows for running containers to be audited and
+modified using Salt, but without running a Salt Minion inside the container.
+Some of the applications include security audits of running containers as
+well as gathering operating data from containers.
+.sp
+This new feature is simple and straightforward, and can be used via a running
+Salt Minion, the Salt Call command, or via Salt SSH. For this tutorial we will
+use the \fIsalt\-call\fP command, but like all salt commands these calls are
+directly translatable to \fIsalt\fP and \fIsalt\-ssh\fP\&.
+.SS Step 1 \- Install Docker
+.sp
+Since setting up Docker is well covered in the Docker documentation we will
+make no such effort to describe it here. Please see the Docker Installation
+Documentation for installing and setting up Docker:
+\fI\%https://docs.docker.com/engine/installation/\fP
+.sp
+The Docker integration also requires that the \fIdocker\-py\fP library is installed.
+This can easily be done using pip or via your system package manager:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+pip install docker\-py
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.SS Step 2 \- Install Salt
+.sp
+For this tutorial we will be using Salt Call, which is available in the
+\fIsalt\-minion\fP package, please follow the Salt Installation docs found here:
+\fI\%https://repo.saltstack.com/\fP
+.SS Step 3 \- Create With Salt States
+.sp
+Next some Salt States are needed, for this example a very basic state which
+installs \fIvim\fP is used, but anything Salt States can do can be done here,
+please see the Salt States Introduction Tutorial to learn more about Salt
+States:
+\fI\%https://docs.saltstack.com/en/stage/getstarted/config/\fP
+.sp
+For this tutorial, simply create a small state file in \fI/srv/salt/vim.sls\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
vim:
- pkg:
- \- installed
- user:
- \- present
+ pkg.installed
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+\fBNOTE:\fP
+.INDENT 0.0
+.INDENT 3.5
+The base image you choose will need to have python 2.6 or 2.7 installed.
+We are hoping to resolve this constraint in a future release.
+.sp
+If \fIbase\fP is omitted the default image used is a minimal openSUSE
+image with Python support, maintained by SUSE
+.UNINDENT
+.UNINDENT
+.sp
+Next run the \fIdocker.sls_build\fP command:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+salt\-call \-\-local dockerng.sls_build test base=my_base_image mods=vim
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Now we have a fresh image called \fItest\fP to work with and vim has been
+installed.
+.SS Step 4 \- Running Commands Inside the Container
+.sp
+Salt can now run remote execution functions inside the container with another
+simple \fIsalt\-call\fP command:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+salt\-call \-\-local dockerng.call test test.ping
+salt\-call \-\-local dockerng.call test network.interfaces
+salt\-call \-\-local dockerng.call test disk.usage
+salt\-call \-\-local dockerng.call test pkg.list_pkgs
+salt\-call \-\-local dockerng.call test service.running httpd
+salt\-call \-\-local dockerng.call test cmd.run \(aqls \-l /etc\(aq
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.SS Automatic Updates / Frozen Deployments
+.sp
+New in version 0.10.3.d.
-fred:
- user:
- \- present
- ssh_auth:
- \- present
- \- name: AAAAB3NzaC...
- \- user: fred
- \- enc: ssh\-dss
- \- require:
- \- user: fred
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.SS YAML supports only plain ASCII
.sp
-According to YAML specification, only ASCII characters can be used.
+Salt has support for the
+\fI\%Esky\fP application freezing and update
+tool. This tool allows one to build a complete zipfile out of the salt scripts
+and all their dependencies \- including shared objects / DLLs.
+.SS Getting Started
.sp
-Within double\-quotes, special characters may be represented with C\-style
-escape sequences starting with a backslash ( \e ).
+To build frozen applications, suitable build environment will be needed for
+each platform. You should probably set up a virtualenv in order to limit the
+scope of Q/A.
.sp
-Examples:
+This process does work on Windows. Directions are available at
+\fI\%https://github.com/saltstack/salt\-windows\-install\fP for details on
+installing Salt in Windows. Only the 32\-bit Python and dependencies have been
+tested, but they have been tested on 64\-bit Windows.
+.sp
+Install \fBbbfreeze\fP, and then \fBesky\fP from PyPI in order to enable the
+\fBbdist_esky\fP command in \fBsetup.py\fP\&. Salt itself must also be installed, in
+addition to its dependencies.
+.SS Building and Freezing
+.sp
+Once you have your tools installed and the environment configured, use
+\fBsetup.py\fP to prepare the distribution files.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
-\- micro: "\eu00b5"
-\- copyright: "\eu00A9"
-\- A: "\ex41"
-\- alpha: "\eu0251"
-\- Alef: "\eu05d0"
+python setup.py sdist
+python setup.py bdist
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
-List of usable \fI\%Unicode characters\fP will help you to identify correct numbers.
-.sp
-Python can also be used to discover the Unicode number for a character:
+Once the distribution files are in place, Esky can be used traverse the module
+tree and pack all the scripts up into a redistributable.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
-repr(u"Text with wrong characters i need to figure out")
+python setup.py bdist_esky
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
-This shell command can find wrong characters in your SLS files:
+There will be an appropriately versioned \fBsalt\-VERSION.zip\fP in \fBdist/\fP if
+everything went smoothly.
+.SS Windows
+.sp
+\fBC:\ePython27\elib\esite\-packages\ezmq\fP will need to be added to the PATH
+variable. This helps bbfreeze find the zmq DLL so it can pack it up.
+.SS Using the Frozen Build
+.sp
+Unpack the zip file in the desired install location. Scripts like
+\fBsalt\-minion\fP and \fBsalt\-call\fP will be in the root of the zip file. The
+associated libraries and bootstrapping will be in the directories at the same
+level. (Check the \fI\%Esky\fP documentation
+for more information)
+.sp
+To support updating your minions in the wild, put the builds on a web server
+that the minions can reach. \fBsalt.modules.saltutil.update()\fP will
+trigger an update and (optionally) a restart of the minion service under the
+new version.
+.SS Troubleshooting
+.SS A Windows minion isn\(aqt responding
+.sp
+The process dispatch on Windows is slower than it is on *nix. It may be
+necessary to add \(aq\-t 15\(aq to salt commands to give minions plenty of time to
+return.
+.SS Windows and the Visual Studio Redist
+.sp
+The Visual C++ 2008 32\-bit redistributable will need to be installed on all
+Windows minions. Esky has an option to pack the library into the zipfile,
+but OpenSSL does not seem to acknowledge the new location. If a
+\fBno OPENSSL_Applink\fP error appears on the console when trying to start a
+frozen minion, the redistributable is not installed.
+.SS Mixed Linux environments and Yum
+.sp
+The Yum Python module doesn\(aqt appear to be available on any of the standard
+Python package mirrors. If RHEL/CentOS systems need to be supported, the frozen
+build should created on that platform to support all the Linux nodes. Remember
+to build the virtualenv with \fB\-\-system\-site\-packages\fP so that the \fByum\fP
+module is included.
+.SS Automatic (Python) module discovery
+.sp
+Automatic (Python) module discovery does not work with the late\-loaded scheme
+that Salt uses for (Salt) modules. Any misbehaving modules will need to be
+explicitly added to the \fBfreezer_includes\fP in Salt\(aqs \fBsetup.py\fP\&. Always
+check the zipped application to make sure that the necessary modules were
+included.
+.SS ESXi Proxy Minion
+.sp
+New in version 2015.8.4.
+
+.sp
+\fBNOTE:\fP
+.INDENT 0.0
+.INDENT 3.5
+This tutorial assumes basic knowledge of Salt. To get up to speed, check
+out the Salt Walkthrough\&.
+.sp
+This tutorial also assumes a basic understanding of Salt Proxy Minions. If
+you\(aqre unfamiliar with Salt\(aqs Proxy Minion system, please read the
+Salt Proxy Minion documentation and the
+Salt Proxy Minion End\-to\-End Example
+tutorial.
+.sp
+The third assumption that this tutorial makes is that you also have a
+basic understanding of ESXi hosts. You can learn more about ESXi hosts on
+\fI\%VMware\(aqs various resources\fP\&.
+.UNINDENT
+.UNINDENT
+.sp
+Salt\(aqs ESXi Proxy Minion allows a VMware ESXi host to be treated as an individual
+Salt Minion, without installing a Salt Minion on the ESXi host.
+.sp
+Since an ESXi host may not necessarily run on an OS capable of hosting a Python
+stack, the ESXi host can\(aqt run a regular Salt Minion directly. Therefore, Salt\(aqs
+Proxy Minion functionality enables you to designate another machine to host a
+proxy process that "proxies" communication from the Salt Master to the ESXi host.
+The master does not know or care that the ESXi target is not a "real" Salt Minion.
+.sp
+More in\-depth conceptual reading on Proxy Minions can be found in the
+Proxy Minion section of Salt\(aqs documentation.
+.sp
+Salt\(aqs ESXi Proxy Minion was added in the 2015.8.4 release of Salt.
+.sp
+\fBNOTE:\fP
+.INDENT 0.0
+.INDENT 3.5
+Be aware that some functionality for the ESXi Proxy Minion may depend on the
+type of license attached the ESXi host(s).
+.sp
+For example, certain services are only available to manipulate service state
+or policies with a VMware vSphere Enterprise or Enterprise Plus license, while
+others are available with a Standard license. The \fBntpd\fP service is restricted
+to an Enterprise Plus license, while \fBssh\fP is available via the Standard
+license.
+.sp
+Please see the \fI\%vSphere Comparison\fP page for more information.
+.UNINDENT
+.UNINDENT
+.SS Dependencies
+.sp
+Manipulation of the ESXi host via a Proxy Minion requires the machine running
+the Proxy Minion process to have the ESXCLI package (and all of it\(aqs dependencies)
+and the pyVmomi Python Library to be installed.
+.SS ESXi Password
+.sp
+The ESXi Proxy Minion uses VMware\(aqs API to perform tasks on the host as if it was
+a regular Salt Minion. In order to access the API that is already running on the
+ESXi host, the ESXi host must have a username and password that is used to log
+into the host. The username is usually \fBroot\fP\&. Before Salt can access the ESXi
+host via VMware\(aqs API, a default password \fImust\fP be set on the host.
+.SS pyVmomi
+.sp
+The pyVmomi Python library must be installed on the machine that is running the
+proxy process. pyVmomi can be installed via pip:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
-find . \-name \(aq*.sls\(aq \-exec grep \-\-color=\(aqauto\(aq \-P \-n \(aq[^\ex00\-\ex7F]\(aq \e{} \e;
+pip install pyVmomi
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
-Alternatively you can toggle the \fIyaml_utf8\fP setting in your master configuration
-file. This is still an experimental setting but it should manage the right
-encoding conversion in salt after yaml states compilations.
-.SS Underscores stripped in Integer Definitions
+\fBNOTE:\fP
+.INDENT 0.0
+.INDENT 3.5
+Version 6.0 of pyVmomi has some problems with SSL error handling on certain
+versions of Python. If using version 6.0 of pyVmomi, the machine that you
+are running the proxy minion process from must have either Python 2.6,
+Python 2.7.9, or newer. This is due to an upstream dependency in pyVmomi 6.0
+that is not supported in Python version 2.7 to 2.7.8. If the
+version of Python running the proxy process is not in the supported range, you
+will need to install an earlier version of pyVmomi. See \fI\%Issue #29537\fP for
+more information.
+.UNINDENT
+.UNINDENT
.sp
-If a definition only includes numbers and underscores, it is parsed by YAML as
-an integer and all underscores are stripped. To ensure the object becomes a
-string, it should be surrounded by quotes. \fI\%More information here\fP\&.
-.sp
-Here\(aqs an example:
+Based on the note above, to install an earlier version of pyVmomi than the
+version currently listed in PyPi, run the following:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
->>> import yaml
->>> yaml.safe_load(\(aq2013_05_10\(aq)
-20130510
->>> yaml.safe_load(\(aq"2013_05_10"\(aq)
-\(aq2013_05_10\(aq
+pip install pyVmomi==5.5.0.2014.1.1
.ft P
.fi
.UNINDENT
.UNINDENT
-.SS Automatic \fBdatetime\fP conversion
.sp
-If there is a value in a YAML file formatted \fB2014\-01\-20 14:23:23\fP or
-similar, YAML will automatically convert this to a Python \fBdatetime\fP object.
-These objects are not msgpack serializable, and so may break core salt
-functionality. If values such as these are needed in a salt YAML file
-(specifically a configuration file), they should be formatted with surrounding
-strings to force YAML to serialize them as strings:
+The 5.5.0.2014.1.1 is a known stable version that the original ESXi Proxy Minion
+was developed against.
+.SS ESXCLI
+.sp
+Currently, about a third of the functions used for the ESXi Proxy Minion require
+the ESXCLI package be installed on the machine running the Proxy Minion process.
+.sp
+The ESXCLI package is also referred to as the VMware vSphere CLI, or vCLI. VMware
+provides vCLI package installation instructions for \fI\%vSphere 5.5\fP and
+\fI\%vSphere 6.0\fP\&.
+.sp
+Once all of the required dependencies are in place and the vCLI package is
+installed, you can check to see if you can connect to your ESXi host by running
+the following command:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
->>> import yaml
->>> yaml.safe_load(\(aq2014\-01\-20 14:23:23\(aq)
-datetime.datetime(2014, 1, 20, 14, 23, 23)
->>> yaml.safe_load(\(aq"2014\-01\-20 14:23:23"\(aq)
-\(aq2014\-01\-20 14:23:23\(aq
+esxcli \-s \-u \-p system syslog config get
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
-Additionally, numbers formatted like \fBXXXX\-XX\-XX\fP will also be converted (or
-YAML will attempt to convert them, and error out if it doesn\(aqt think the date
-is a real one). Thus, for example, if a minion were to have an ID of
-\fB4017\-16\-20\fP the minion would not start because YAML would complain that the
-date was out of range. The workaround is the same, surround the offending
-string with quotes:
+If the connection was successful, ESXCLI was successfully installed on your system.
+You should see output related to the ESXi host\(aqs syslog configuration.
+.SS Configuration
+.sp
+There are several places where various configuration values need to be set in
+order for the ESXi Proxy Minion to run and connect properly.
+.SS Proxy Config File
+.sp
+On the machine that will be running the Proxy Minon process(es), a proxy config
+file must be in place. This file should be located in the \fB/etc/salt/\fP directory
+and should be named \fBproxy\fP\&. If the file is not there by default, create it.
+.sp
+This file should contain the location of your Salt Master that the Salt Proxy
+will connect to.
+.sp
+Example Proxy Config File:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
->>> import yaml
->>> yaml.safe_load(\(aq4017\-16\-20\(aq)
-Traceback (most recent call last):
- File "", line 1, in
- File "/usr/local/lib/python2.7/site\-packages/yaml/__init__.py", line 93, in safe_load
- return load(stream, SafeLoader)
- File "/usr/local/lib/python2.7/site\-packages/yaml/__init__.py", line 71, in load
- return loader.get_single_data()
- File "/usr/local/lib/python2.7/site\-packages/yaml/constructor.py", line 39, in get_single_data
- return self.construct_document(node)
- File "/usr/local/lib/python2.7/site\-packages/yaml/constructor.py", line 43, in construct_document
- data = self.construct_object(node)
- File "/usr/local/lib/python2.7/site\-packages/yaml/constructor.py", line 88, in construct_object
- data = constructor(self, node)
- File "/usr/local/lib/python2.7/site\-packages/yaml/constructor.py", line 312, in construct_yaml_timestamp
- return datetime.date(year, month, day)
-ValueError: month must be in 1..12
->>> yaml.safe_load(\(aq"4017\-16\-20"\(aq)
-\(aq4017\-16\-20\(aq
+# /etc/salt/proxy
+
+master:
.ft P
.fi
.UNINDENT
.UNINDENT
-.SS Keys Limited to 1024 Characters
+.SS Pillar Profiles
.sp
-Simple keys are limited to a single line and cannot be longer that 1024 characters.
-This is a limitation from PyYaml, as seen in a comment in \fI\%PyYAML\(aqs code\fP, and
-applies to anything parsed by YAML in Salt.
-.SS Live Python Debug Output
-.sp
-If the minion or master seems to be unresponsive, a SIGUSR1 can be passed to
-the processes to display where in the code they are running. If encountering a
-situation like this, this debug information can be invaluable. First make
-sure the master of minion are running in the foreground:
+Proxy minions get their configuration from Salt\(aqs Pillar. Every proxy must
+have a stanza in Pillar and a reference in the Pillar top\-file that matches
+the Proxy ID. At a minimum for communication with the ESXi host, the pillar
+should look like this:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
-salt\-master \-l debug
-salt\-minion \-l debug
+proxy:
+ proxytype: esxi
+ host:
+ username:
+ passwords:
+ \- first_password
+ \- second_password
+ \- third_password
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
-Then pass the signal to the master or minion when it seems to be unresponsive:
+Some other optional settings are \fBprotocol\fP and \fBport\fP\&. These can be added
+to the pillar configuration.
+.SS proxytype
+.sp
+The \fBproxytype\fP key and value pair is critical, as it tells Salt which
+interface to load from the \fBproxy\fP directory in Salt\(aqs install hierarchy,
+or from \fB/srv/salt/_proxy\fP on the Salt Master (if you have created your
+own proxy module, for example). To use this ESXi Proxy Module, set this to
+\fBesxi\fP\&.
+.SS host
+.sp
+The location, or ip/dns, of the ESXi host. Required.
+.SS username
+.sp
+The username used to login to the ESXi host, such as \fBroot\fP\&. Required.
+.SS passwords
+.sp
+A list of passwords to be used to try and login to the ESXi host. At least
+one password in this list is required.
+.sp
+The proxy integration will try the passwords listed in order. It is
+configured this way so you can have a regular password and the password you
+may be updating for an ESXi host either via the
+\fBvsphere.update_host_password\fP
+execution module function or via the
+\fBesxi.password_present\fP state
+function. This way, after the password is changed, you should not need to
+restart the proxy minion\-\-it should just pick up the new password
+provided in the list. You can then change pillar at will to move that
+password to the front and retire the unused ones.
+.sp
+Use\-case/reasoning for using a list of passwords: You are setting up an
+ESXi host for the first time, and the host comes with a default password.
+You know that you\(aqll be changing this password during your initial setup
+from the default to a new password. If you only have one password option,
+and if you have a state changing the password, any remote execution commands
+or states that run after the password change will not be able to run on the
+host until the password is updated in Pillar and the Proxy Minion process is
+restarted.
+.sp
+This allows you to use any number of potential fallback passwords.
+.sp
+\fBNOTE:\fP
+.INDENT 0.0
+.INDENT 3.5
+When a password is changed on the host to one in the list of possible
+passwords, the further down on the list the password is, the longer
+individual commands will take to return. This is due to the nature of
+pyVmomi\(aqs login system. We have to wait for the first attempt to fail
+before trying the next password on the list.
+.sp
+This scenario is especially true, and even slower, when the proxy
+minion first starts. If the correct password is not the first password
+on the list, it may take up to a minute for \fBtest.ping\fP to respond
+with a \fBTrue\fP result. Once the initial authorization is complete, the
+responses for commands will be a little faster.
+.sp
+To avoid these longer waiting periods, SaltStack recommends moving the
+correct password to the top of the list and restarting the proxy minion
+at your earliest convenience.
+.UNINDENT
+.UNINDENT
+.SS protocol
+.sp
+If the ESXi host is not using the default protocol, set this value to an
+alternate protocol. Default is \fBhttps\fP\&. For example:
+.SS port
+.sp
+If the ESXi host is not using the default port, set this value to an
+alternate port. Default is \fB443\fP\&.
+.SS Example Configuration Files
+.sp
+An example of all of the basic configurations that need to be in place before
+starting the Proxy Minion processes includes the Proxy Config File, Pillar
+Top File, and any individual Proxy Minion Pillar files.
+.sp
+In this example, we\(aqll assuming there are two ESXi hosts to connect to. Therefore,
+we\(aqll be creating two Proxy Minion config files, one config for each ESXi host.
+.sp
+Proxy Config File:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
-killall \-SIGUSR1 salt\-master
-killall \-SIGUSR1 salt\-minion
+# /etc/salt/proxy
+
+master:
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
-Also under BSD and macOS in addition to SIGUSR1 signal, debug subroutine set
-up for SIGINFO which has an advantage of being sent by Ctrl+T shortcut.
-.sp
-When filing an issue or sending questions to the mailing list for a problem
-with an unresponsive daemon this information can be invaluable.
-.SS Salt 0.16.x minions cannot communicate with a 0.17.x master
-.sp
-As of release 0.17.1 you can no longer run different versions of Salt on your
-Master and Minion servers. This is due to a protocol change for security
-purposes. The Salt team will continue to attempt to ensure versions are as
-backwards compatible as possible.
-.SS Debugging the Master and Minion
-.sp
-A list of common master and
-minion troubleshooting steps provide a
-starting point for resolving issues you may encounter.
-.SS Frequently Asked Questions
-.SS FAQ
+Pillar Top File:
.INDENT 0.0
-.IP \(bu 2
-\fI\%Frequently Asked Questions\fP
-.INDENT 2.0
-.IP \(bu 2
-\fI\%Is Salt open\-core?\fP
-.IP \(bu 2
-\fI\%I think I found a bug! What should I do?\fP
-.IP \(bu 2
-\fI\%What ports should I open on my firewall?\fP
-.IP \(bu 2
-\fI\%I\(aqm seeing weird behavior (including but not limited to packages not installing their users properly)\fP
-.IP \(bu 2
-\fI\%My script runs every time I run a state.apply. Why?\fP
-.IP \(bu 2
-\fI\%When I run test.ping, why don\(aqt the Minions that aren\(aqt responding return anything? Returning False would be helpful.\fP
-.IP \(bu 2
-\fI\%How does Salt determine the Minion\(aqs id?\fP
-.IP \(bu 2
-\fI\%I\(aqm trying to manage packages/services but I get an error saying that the state is not available. Why?\fP
-.IP \(bu 2
-\fI\%Why aren\(aqt my custom modules/states/etc. available on my Minions?\fP
-.IP \(bu 2
-\fI\%Module X isn\(aqt available, even though the shell command it uses is installed. Why?\fP
-.IP \(bu 2
-\fI\%Can I run different versions of Salt on my Master and Minion?\fP
-.IP \(bu 2
-\fI\%Does Salt support backing up managed files?\fP
-.IP \(bu 2
-\fI\%Is it possible to deploy a file to a specific minion, without other minions having access to it?\fP
-.IP \(bu 2
-\fI\%What is the best way to restart a Salt Minion daemon using Salt after upgrade?\fP
-.INDENT 2.0
-.IP \(bu 2
-\fI\%Upgrade without automatic restart\fP
-.IP \(bu 2
-\fI\%Restart using states\fP
-.IP \(bu 2
-\fI\%Restart using remote executions\fP
-.UNINDENT
-.IP \(bu 2
-\fI\%Salting the Salt Master\fP
-.IP \(bu 2
-\fI\%Is Targeting using Grain Data Secure?\fP
-.IP \(bu 2
-\fI\%Why Did the Value for a Grain Change on Its Own?\fP
+.INDENT 3.5
+.sp
+.nf
+.ft C
+# /srv/pillar/top.sls
+
+base:
+ \(aqesxi\-1\(aq:
+ \- esxi\-1
+ \(aqesxi\-2\(aq:
+ \- esxi\-2
+.ft P
+.fi
.UNINDENT
.UNINDENT
-.SS Is Salt open\-core?
.sp
-No. Salt is 100% committed to being open\-source, including all of our APIs. It
-is developed under the \fI\%Apache 2.0 license\fP, allowing it to be used in both
-open and proprietary projects.
+Pillar Config File for the first ESXi host, esxi\-1:
+.INDENT 0.0
+.INDENT 3.5
.sp
-To expand on this a little:
+.nf
+.ft C
+# /srv/pillar/esxi\-1.sls
+
+proxy:
+ proxytype: esxi
+ host: esxi\-1.example.com
+ username: \(aqroot\(aq
+ passwords:
+ \- bad\-password\-1
+ \- backup\-bad\-password\-1
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
.sp
-There is much argument over the actual definition of "open core". From our standpoint, Salt is open source because
+Pillar Config File for the second ESXi host, esxi\-2:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+# /srv/pillar/esxi\-2.sls
+
+proxy:
+ proxytype: esxi
+ host: esxi\-2.example.com
+ username: \(aqroot\(aq
+ passwords:
+ \- bad\-password\-2
+ \- backup\-bad\-password\-2
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.SS Starting the Proxy Minion
+.sp
+Once all of the correct configuration files are in place, it is time to start the
+proxy processes!
.INDENT 0.0
.IP 1. 3
-It is a standalone product that anyone is free to use.
+First, make sure your Salt Master is running.
.IP 2. 3
-It is developed in the open with contributions accepted from the community for the good of the project.
-.IP 3. 3
-There are no features of Salt itself that are restricted to separate proprietary products distributed by SaltStack, Inc.
-.IP 4. 3
-Because of our Apache 2.0 license, Salt can be used as the foundation for a project or even a proprietary tool.
-.IP 5. 3
-Our APIs are open and documented (any lack of documentation is an oversight as opposed to an intentional decision by SaltStack the company) and available for use by anyone.
+Start the first Salt Proxy, in debug mode, by giving the Proxy Minion process
+and ID that matches the config file name created in the \fI\%Configuration\fP section.
.UNINDENT
-.sp
-SaltStack the company does make proprietary products which use Salt and its libraries, like company is free to do, but we do so via the APIs, NOT by forking Salt and creating a different, closed\-source version of it for paying customers.
-.SS I think I found a bug! What should I do?
-.sp
-The salt\-users mailing list as well as the salt IRC channel can both be helpful
-resources to confirm if others are seeing the issue and to assist with
-immediate debugging.
-.sp
-To report a bug to the Salt project, please follow the instructions in
-reporting a bug\&.
-.SS What ports should I open on my firewall?
-.sp
-Minions need to be able to connect to the Master on TCP ports 4505 and 4506.
-Minions do not need any inbound ports open. More detailed information on
-firewall settings can be found here\&.
-.SS I\(aqm seeing weird behavior (including but not limited to packages not installing their users properly)
-.sp
-This is often caused by SELinux. Try disabling SELinux or putting it in
-permissive mode and see if the weird behavior goes away.
-.SS My script runs every time I run a \fIstate.apply\fP\&. Why?
-.sp
-You are probably using \fBcmd.run\fP rather than
-\fBcmd.wait\fP\&. A \fBcmd.wait\fP state will only run when there has been a change in a
-state that it is watching.
-.sp
-A \fBcmd.run\fP state will run the corresponding command
-\fIevery time\fP (unless it is prevented from running by the \fBunless\fP or \fBonlyif\fP
-arguments).
-.sp
-More details can be found in the documentation for the \fBcmd\fP states.
-.SS When I run \fItest.ping\fP, why don\(aqt the Minions that aren\(aqt responding return anything? Returning \fBFalse\fP would be helpful.
-.sp
-When you run \fItest.ping\fP the Master tells Minions to run commands/functions,
-and listens for the return data, printing it to the screen when it is received.
-If it doesn\(aqt receive anything back, it doesn\(aqt have anything to display for
-that Minion.
-.sp
-There are a couple options for getting information on Minions that are not
-responding. One is to use the verbose (\fB\-v\fP) option when you run salt
-commands, as it will display "Minion did not return" for any Minions which time
-out.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
-salt \-v \(aq*\(aq pkg.install zsh
+salt\-proxy \-\-proxyid=\(aqesxi\-1\(aq \-l debug
.ft P
.fi
.UNINDENT
.UNINDENT
-.sp
-Another option is to use the \fBmanage.down\fP
-runner:
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-salt\-run manage.down
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-Also, if the Master is under heavy load, it is possible that the CLI will exit
-without displaying return data for all targeted Minions. However, this doesn\(aqt
-mean that the Minions did not return; this only means that the Salt CLI timed
-out waiting for a response. Minions will still send their return data back to
-the Master once the job completes. If any expected Minions are missing from the
-CLI output, the \fBjobs.list_jobs\fP runner can
-be used to show the job IDs of the jobs that have been run, and the
-\fBjobs.lookup_jid\fP runner can be used to get
-the return data for that job.
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-salt\-run jobs.list_jobs
-salt\-run jobs.lookup_jid 20130916125524463507
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-If you find that you are often missing Minion return data on the CLI, only to
-find it with the jobs runners, then this may be a sign that the
-\fBworker_threads\fP value may need to be increased in the master
-config file. Additionally, running your Salt CLI commands with the \fB\-t\fP
-option will make Salt wait longer for the return data before the CLI command
-exits. For instance, the below command will wait up to 60 seconds for the
-Minions to return:
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-salt \-t 60 \(aq*\(aq test.ping
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.SS How does Salt determine the Minion\(aqs id?
-.sp
-If the Minion id is not configured explicitly (using the \fBid\fP
-parameter), Salt will determine the id based on the hostname. Exactly how this
-is determined varies a little between operating systems and is described in
-detail here\&.
-.SS I\(aqm trying to manage packages/services but I get an error saying that the state is not available. Why?
-.sp
-Salt detects the Minion\(aqs operating system and assigns the correct package or
-service management module based on what is detected. However, for certain custom
-spins and OS derivatives this detection fails. In cases like this, an issue
-should be opened on our \fI\%tracker\fP, with the following information:
.INDENT 0.0
.IP 1. 3
-The output of the following command:
-.INDENT 3.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-salt grains.items | grep os
-.ft P
-.fi
+Accept the \fBesxi\-1\fP Proxy Minion\(aqs key on the Salt Master:
.UNINDENT
-.UNINDENT
-.IP 2. 3
-The contents of \fB/etc/lsb\-release\fP, if present on the Minion.
-.UNINDENT
-.SS Why aren\(aqt my custom modules/states/etc. available on my Minions?
-.sp
-Custom modules are synced to Minions when
-\fBsaltutil.sync_modules\fP,
-or \fBsaltutil.sync_all\fP is run.
-Custom modules are also synced by \fBstate.apply\fP when run without
-any arguments.
-.sp
-Similarly, custom states are synced to Minions
-when \fBstate.apply\fP,
-\fBsaltutil.sync_states\fP, or
-\fBsaltutil.sync_all\fP is run.
-.sp
-Custom states are also synced by \fBstate.apply\fP
-when run without any arguments.
-.sp
-Other custom types (renderers, outputters, etc.) have similar behavior, see the
-documentation for the \fBsaltutil\fP module for more
-information.
-.sp
-This reactor example can be used to automatically
-sync custom types when the minion connects to the master, to help with this
-chicken\-and\-egg issue.
-.SS Module \fBX\fP isn\(aqt available, even though the shell command it uses is installed. Why?
-.sp
-This is most likely a PATH issue. Did you custom\-compile the software which the
-module requires? RHEL/CentOS/etc. in particular override the root user\(aqs path
-in \fB/etc/init.d/functions\fP, setting it to \fB/sbin:/usr/sbin:/bin:/usr/bin\fP,
-making software installed into \fB/usr/local/bin\fP unavailable to Salt when the
-Minion is started using the initscript. In version 2014.1.0, Salt will have a
-better solution for these sort of PATH\-related issues, but recompiling the
-software to install it into a location within the PATH should resolve the
-issue in the meantime. Alternatively, you can create a symbolic link within the
-PATH using a \fBfile.symlink\fP state.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
-/usr/bin/foo:
- file.symlink:
- \- target: /usr/local/bin/foo
+# salt\-key \-L
+Accepted Keys:
+Denied Keys:
+Unaccepted Keys:
+esxi\-1
+Rejected Keys:
+#
+# salt\-key \-a esxi\-1
+The following keys are going to be accepted:
+Unaccepted Keys:
+esxi\-1
+Proceed? [n/Y] y
+Key for minion esxi\-1 accepted.
.ft P
.fi
.UNINDENT
.UNINDENT
-.SS Can I run different versions of Salt on my Master and Minion?
-.sp
-This depends on the versions. In general, it is recommended that Master and
-Minion versions match.
-.sp
-When upgrading Salt, the master(s) should always be upgraded first. Backwards
-compatibility for minions running newer versions of salt than their masters is
-not guaranteed.
-.sp
-Whenever possible, backwards compatibility between new masters
-and old minions will be preserved. Generally, the only exception to this
-policy is in case of a security vulnerability.
-.sp
-Recent examples of backwards compatibility breakage include the 0.17.1 release
-(where all backwards compatibility was broken due to a security fix), and the
-2014.1.0 release (which retained compatibility between 2014.1.0 masters and
-0.17 minions, but broke compatibility for 2014.1.0 minions and older masters).
-.SS Does Salt support backing up managed files?
-.sp
-Yes. Salt provides an easy to use addition to your file.managed states that
-allow you to back up files via backup_mode,
-backup_mode can be configured on a per state basis, or in the minion config
-(note that if set in the minion config this would simply be the default
-method to use, you still need to specify that the file should be backed up!).
-.SS Is it possible to deploy a file to a specific minion, without other minions having access to it?
-.sp
-The Salt fileserver does not yet support access control, but it is still
-possible to do this. As of Salt 2015.5.0, the
-\fBfile_tree\fP external pillar is available, and
-allows the contents of a file to be loaded as Pillar data. This external pillar
-is capable of assigning Pillar values both to individual minions, and to
-nodegroups\&. See the \fBdocumentation\fP for details on how to set this up.
-.sp
-Once the external pillar has been set up, the data can be pushed to a minion
-via a \fBfile.managed\fP state, using the
-\fBcontents_pillar\fP argument:
+.INDENT 0.0
+.IP 1. 3
+Repeat for the second Salt Proxy, this time we\(aqll run the proxy process as a
+daemon, as an example.
+.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
-/etc/my_super_secret_file:
- file.managed:
- \- user: secret
- \- group: secret
- \- mode: 600
- \- contents_pillar: secret_files:my_super_secret_file
+salt\-proxy \-\-proxyid=\(aqesxi\-2\(aq \-d
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.INDENT 0.0
+.IP 1. 3
+Accept the \fBesxi\-2\fP Proxy Minion\(aqs key on the Salt Master:
+.UNINDENT
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+# salt\-key \-L
+Accepted Keys:
+esxi\-1
+Denied Keys:
+Unaccepted Keys:
+esxi\-2
+Rejected Keys:
+#
+# salt\-key \-a esxi\-1
+The following keys are going to be accepted:
+Unaccepted Keys:
+esxi\-2
+Proceed? [n/Y] y
+Key for minion esxi\-1 accepted.
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.INDENT 0.0
+.IP 1. 3
+Check and see if your Proxy Minions are responding:
+.UNINDENT
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+# salt \(aqesxi\-*\(aq test.ping
+esxi\-1:
+ True
+esxi\-3:
+ True
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.SS Executing Commands
+.sp
+Now that you\(aqve configured your Proxy Minions and have them responding successfully
+to a \fBtest.ping\fP, we can start executing commands against the ESXi hosts via Salt.
+.sp
+It\(aqs important to understand how this particular proxy works, and there are a couple
+of important pieces to be aware of in order to start running remote execution and
+state commands against the ESXi host via a Proxy Minion: the
+\fI\%vSphere Execution Module\fP, the \fI\%ESXi Execution Module\fP, and the \fI\%ESXi State Module\fP\&.
+.SS vSphere Execution Module
+.sp
+The \fBSalt.modules.vsphere\fP is a
+standard Salt execution module that does the bulk of the work for the ESXi Proxy
+Minion. If you pull up the docs for it you\(aqll see that almost every function in
+the module takes credentials (\fBusername\fP and \fBpassword\fP) and a target \fBhost\fP
+argument. When credentials and a host aren\(aqt passed, Salt runs commands
+through \fBpyVmomi\fP or \fBESXCLI\fP against the local machine. If you wanted,
+you could run functions from this module on any machine where an appropriate
+version of \fBpyVmomi\fP and \fBESXCLI\fP are installed, and that machine would reach
+out over the network and communicate with the ESXi host.
+.sp
+You\(aqll notice that most of the functions in the vSphere module require a \fBhost\fP,
+\fBusername\fP, and \fBpassword\fP\&. These parameters are contained in the Pillar files and
+passed through to the function via the proxy process that is already running. You don\(aqt
+need to provide these parameters when you execute the commands. See the
+\fI\%Running Remote Execution Commands\fP section below for an example.
+.SS ESXi Execution Module
+.sp
+In order for the Pillar information set up in the \fI\%Configuration\fP section above to
+be passed to the function call in the vSphere Execution Module, the
+\fBsalt.modules.esxi\fP execution module acts
+as a "shim" between the vSphere execution module functions and the proxy process.
+.sp
+The "shim" takes the authentication credentials specified in the Pillar files and
+passes them through to the \fBhost\fP, \fBusername\fP, \fBpassword\fP, and optional
+\fBprotocol\fP and \fBport\fP options required by the vSphere Execution Module functions.
+.sp
+If the function takes more positional, or keyword, arguments you can append them
+to the call. It\(aqs this shim that speaks to the ESXi host through the proxy, arranging
+for the credentials and hostname to be pulled from the Pillar section for the ESXi
+Proxy Minion.
+.sp
+Because of the presence of the shim, to lookup documentation for what
+functions you can use to interface with the ESXi host, you\(aqll want to
+look in \fBsalt.modules.vsphere\fP
+instead of \fBsalt.modules.esxi\fP\&.
+.SS Running Remote Execution Commands
+.sp
+To run commands from the Salt Master to execute, via the ESXi Proxy Minion, against
+the ESXi host, you use the \fBesxi.cmd \fP syntax to call
+functions located in the vSphere Execution Module. Both args and kwargs needed
+for various vsphere execution module functions must be passed through in a kwarg\-
+type manor. For example:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+salt \(aqesxi\-*\(aq esxi.cmd system_info
+salt \(aqexsi\-*\(aq esxi.cmd get_service_running service_name=\(aqssh\(aq
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.SS ESXi State Module
+.sp
+The ESXi State Module functions similarly to other state modules. The "shim" provided
+by the \fI\%ESXi Execution Module\fP passes the necessary \fBhost\fP, \fBusername\fP, and
+\fBpassword\fP credentials through, so those options don\(aqt need to be provided in the
+state. Other than that, state files are written and executed just like any other
+Salt state. See the \fBsalt.modules.esxi\fP state
+for ESXi state functions.
+.sp
+The follow state file is an example of how to configure various pieces of an ESXi host
+including enabling SSH, uploading and SSH key, configuring a coredump network config,
+syslog, ntp, enabling VMotion, resetting a host password, and more.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+# /srv/salt/configure\-esxi.sls
+
+configure\-host\-ssh:
+ esxi.ssh_configured:
+ \- service_running: True
+ \- ssh_key_file: /etc/salt/ssh_keys/my_key.pub
+ \- service_policy: \(aqautomatic\(aq
+ \- service_restart: True
+ \- certificate_verify: True
+
+configure\-host\-coredump:
+ esxi.coredump_configured:
+ \- enabled: True
+ \- dump_ip: \(aqmy\-coredump\-ip.example.com\(aq
+
+configure\-host\-syslog:
+ esxi.syslog_configured:
+ \- syslog_configs:
+ loghost: ssl://localhost:5432,tcp://10.1.0.1:1514
+ default\-timeout: 120
+ \- firewall: True
+ \- reset_service: True
+ \- reset_syslog_config: True
+ \- reset_configs: loghost,default\-timeout
+
+configure\-host\-ntp:
+ esxi.ntp_configured:
+ \- service_running: True
+ \- ntp_servers:
+ \- 192.174.1.100
+ \- 192.174.1.200
+ \- service_policy: \(aqautomatic\(aq
+ \- service_restart: True
+
+configure\-vmotion:
+ esxi.vmotion_configured:
+ \- enabled: True
+
+configure\-host\-vsan:
+ esxi.vsan_configured:
+ \- enabled: True
+ \- add_disks_to_vsan: True
+
+configure\-host\-password:
+ esxi.password_present:
+ \- password: \(aqnew\-bad\-password\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
-In this example, the source file would be located in a directory called
-\fBsecret_files\fP underneath the file_tree path for the minion. The syntax for
-specifying the pillar variable is the same one used for \fBpillar.get\fP, with a colon representing a nested dictionary.
+States are called via the ESXi Proxy Minion just as they would on a regular minion.
+For example:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+salt \(aqesxi\-*\(aq state.sls configure\-esxi test=true
+salt \(aqesxi\-*\(aq state.sls configure\-esxi
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.SS Relevant Salt Files and Resources
+.INDENT 0.0
+.IP \(bu 2
+\fBESXi Proxy Minion\fP
+.IP \(bu 2
+\fBESXi Execution Module\fP
+.IP \(bu 2
+\fBESXi State Module\fP
+.IP \(bu 2
+Salt Proxy Minion Docs
+.IP \(bu 2
+Salt Proxy Minion End\-to\-End Example
+.IP \(bu 2
+\fBvSphere Execution Module\fP
+.UNINDENT
+.SS Installing and Configuring Halite
.sp
\fBWARNING:\fP
.INDENT 0.0
.INDENT 3.5
-Deploying binary contents using the \fBfile.managed\fP state is only supported in Salt 2015.8.4 and
-newer.
-.UNINDENT
-.UNINDENT
-.SS What is the best way to restart a Salt Minion daemon using Salt after upgrade?
+Halite is deprecated
.sp
-Updating the \fBsalt\-minion\fP package requires a restart of the \fBsalt\-minion\fP
-service. But restarting the service while in the middle of a state run
-interrupts the process of the Minion running states and sending results back to
-the Master. A common way to workaround that is to schedule restarting the
-Minion service in the background by issuing a \fBsalt\-call\fP command calling
-\fBservice.restart\fP function. This prevents the Minion being disconnected from
-the Master immediately. Otherwise you would get
-\fBMinion did not return. [Not connected]\fP message as the result of a state run.
-.SS Upgrade without automatic restart
-.sp
-Doing the Minion upgrade seems to be a simplest state in your SLS file at
-first. But the operating systems such as Debian GNU/Linux, Ubuntu and their
-derivatives start the service after the package installation by default.
-To prevent this, we need to create policy layer which will prevent the Minion
-service to restart right after the upgrade:
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-{%\- if grains[\(aqos_family\(aq] == \(aqDebian\(aq %}
-
-Disable starting services:
- file.managed:
- \- name: /usr/sbin/policy\-rc.d
- \- user: root
- \- group: root
- \- mode: 0755
- \- contents:
- \- \(aq#!/bin/sh\(aq
- \- exit 101
- # do not touch if already exists
- \- replace: False
- \- prereq:
- \- pkg: Upgrade Salt Minion
-
-{%\- endif %}
-
-Upgrade Salt Minion:
- pkg.installed:
- \- name: salt\-minion
- \- version: 2016.11.3{% if grains[\(aqos_family\(aq] == \(aqDebian\(aq %}+ds\-1{% endif %}
- \- order: last
-
-Enable Salt Minion:
- service.enabled:
- \- name: salt\-minion
- \- require:
- \- pkg: Upgrade Salt Minion
-
-{%\- if grains[\(aqos_family\(aq] == \(aqDebian\(aq %}
-
-Enable starting services:
- file.absent:
- \- name: /usr/sbin/policy\-rc.d
- \- onchanges:
- \- pkg: Upgrade Salt Minion
-
-{%\- endif %}
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.SS Restart using states
-.sp
-Now we can apply the workaround to restart the Minion in reliable way.
-The following example works on UNIX\-like operating systems:
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-{%\- if grains[\(aqos\(aq] != \(aqWindows\(aq %}
-Restart Salt Minion:
- cmd.run:
- \- name: \(aqsalt\-call service.restart salt\-minion\(aq
- \- bg: True
- \- onchanges:
- \- pkg: Upgrade Salt Minion
-{%\- endif %}
-.ft P
-.fi
+The Halite project is retired. The code will remain available on GitHub.
.UNINDENT
.UNINDENT
.sp
-Note that restarting the \fBsalt\-minion\fP service on Windows operating systems is
-not always necessary when performing an upgrade. The installer stops the
-\fBsalt\-minion\fP service, removes it, deletes the contents of the \fB\esalt\ebin\fP
-directory, installs the new code, re\-creates the \fBsalt\-minion\fP service, and
-starts it (by default). The restart step \fBwould\fP be necessary during the
-upgrade process, however, if the minion config was edited after the upgrade or
-installation. If a minion restart is necessary, the state above can be edited
-as follows:
-.INDENT 0.0
-.INDENT 3.5
+In this tutorial, we\(aqll walk through installing and setting up Halite. The
+current version of Halite is considered pre\-alpha and is supported only in Salt
+\fBv2014.1.0\fP or greater. Additional information is available on GitHub:
+\fI\%https://github.com/saltstack/halite\fP
.sp
-.nf
-.ft C
-Restart Salt Minion:
- cmd.run:
-{%\- if grains[\(aqkernel\(aq] == \(aqWindows\(aq %}
- \- name: \(aqC:\esalt\esalt\-call.bat service.restart salt\-minion\(aq
-{%\- else %}
- \- name: \(aqsalt\-call service.restart salt\-minion\(aq
-{%\- endif %}
- \- bg: True
- \- onchanges:
- \- pkg: Upgrade Salt Minion
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-However, it requires more advanced tricks to upgrade from legacy version of
-Salt (before \fB2016.3.0\fP) on UNIX\-like operating systems, where executing
-commands in the background is not supported. You also may need to schedule
-restarting the Minion service using masterless mode after all other states have been applied for Salt
-versions earlier than \fB2016.11.0\fP\&. This allows the Minion to keep the
-connection to the Master alive for being able to report the final results back
-to the Master, while the service is restarting in the background. This state
-should run last or watch for the \fBpkg\fP state changes:
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-Restart Salt Minion:
- cmd.run:
-{%\- if grains[\(aqkernel\(aq] == \(aqWindows\(aq %}
- \- name: \(aqstart powershell "Restart\-Service \-Name salt\-minion"\(aq
-{%\- else %}
- # fork and disown the process
- \- name: |\-
- exec 0>&\- # close stdin
- exec 1>&\- # close stdout
- exec 2>&\- # close stderr
- nohup salt\-call \-\-local service.restart salt\-minion &
-{%\- endif %}
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.SS Restart using remote executions
-.sp
-Restart the Minion from the command line:
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-salt \-G kernel:Windows cmd.run_bg \(aqC:\esalt\esalt\-call.bat service.restart salt\-minion\(aq
-salt \-C \(aqnot G@kernel:Windows\(aq cmd.run_bg \(aqsalt\-call service.restart salt\-minion\(aq
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.SS Salting the Salt Master
-.sp
-In order to configure a master server via states, the Salt master can also be
-"salted" in order to enforce state on the Salt master as well as the Salt
-minions. Salting the Salt master requires a Salt minion to be installed on
-the same machine as the Salt master. Once the Salt minion is installed, the
-minion configuration file must be pointed to the local Salt master:
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-master: 127.0.0.1
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-Once the Salt master has been "salted" with a Salt minion, it can be targeted
-just like any other minion. If the minion on the salted master is running, the
-minion can be targeted via any usual \fBsalt\fP command. Additionally, the
-\fBsalt\-call\fP command can execute operations to enforce state on the salted
-master without requiring the minion to be running.
-.sp
-More information about salting the Salt master can be found in the salt\-formula
-for salt itself:
-.sp
-\fI\%https://github.com/saltstack\-formulas/salt\-formula\fP
-.sp
-Restarting the \fBsalt\-master\fP service using execution module or application of
-state could be done the same way as for the Salt minion described \fI\%above\fP\&.
-.SS Is Targeting using Grain Data Secure?
-.sp
-Because grains can be set by users that have access to the minion configuration
-files on the local system, grains are considered less secure than other
-identifiers in Salt. Use caution when targeting sensitive operations or setting
-pillar values based on grain data.
-.sp
-The only grain which can be safely used is \fBgrains[\(aqid\(aq]\fP which contains the Minion ID.
-.sp
-When possible, you should target sensitive operations and data using the Minion
-ID. If the Minion ID of a system changes, the Salt Minion\(aqs public key must be
-re\-accepted by an administrator on the Salt Master, making it less vulnerable
-to impersonation attacks.
-.SS Why Did the Value for a Grain Change on Its Own?
-.sp
-This is usually the result of an upstream change in an OS distribution that
-replaces or removes something that Salt was using to detect the grain.
-Fortunately, when this occurs, you can use Salt to fix it with a command
-similar to the following:
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-salt \-G \(aqgrain:ChangedValue\(aq grains.setvals "{\(aqgrain\(aq: \(aqOldValue\(aq}"
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-(Replacing \fIgrain\fP, \fIChangedValue\fP, and \fIOldValue\fP with
-the grain and values that you want to change / set.)
-.sp
-You should also \fI\%file an issue\fP
-describing the change so it can be fixed in Salt.
-.SS Salt Best Practices
-.sp
-Salt\(aqs extreme flexibility leads to many questions concerning the structure of
-configuration files.
-.sp
-This document exists to clarify these points through examples and
-code.
-.SS General rules
-.INDENT 0.0
-.IP 1. 3
-Modularity and clarity should be emphasized whenever possible.
-.IP 2. 3
-Create clear relations between pillars and states.
-.IP 3. 3
-Use variables when it makes sense but don\(aqt overuse them.
-.IP 4. 3
-Store sensitive data in pillar.
-.IP 5. 3
-Don\(aqt use grains for matching in your pillar top file for any sensitive
-pillars.
-.UNINDENT
-.SS Structuring States and Formulas
-.sp
-When structuring Salt States and Formulas it is important to begin with the
-directory structure. A proper directory structure clearly defines the
-functionality of each state to the user via visual inspection of the state\(aqs
-name.
-.sp
-Reviewing the \fI\%MySQL Salt Formula\fP
-it is clear to see the benefits to the end\-user when reviewing a sample of the
-available states:
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-/srv/salt/mysql/files/
-/srv/salt/mysql/client.sls
-/srv/salt/mysql/map.jinja
-/srv/salt/mysql/python.sls
-/srv/salt/mysql/server.sls
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-This directory structure would lead to these states being referenced in a top
-file in the following way:
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-base:
- \(aqweb*\(aq:
- \- mysql.client
- \- mysql.python
- \(aqdb*\(aq:
- \- mysql.server
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-This clear definition ensures that the user is properly informed of what each
-state will do.
-.sp
-Another example comes from the \fI\%vim\-formula\fP:
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-/srv/salt/vim/files/
-/srv/salt/vim/absent.sls
-/srv/salt/vim/init.sls
-/srv/salt/vim/map.jinja
-/srv/salt/vim/nerdtree.sls
-/srv/salt/vim/pyflakes.sls
-/srv/salt/vim/salt.sls
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-Once again viewing how this would look in a top file:
-.sp
-/srv/salt/top.sls:
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-base:
- \(aqweb*\(aq:
- \- vim
- \- vim.nerdtree
- \- vim.pyflakes
- \- vim.salt
- \(aqdb*\(aq:
- \- vim.absent
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-The usage of a clear top\-level directory as well as properly named states
-reduces the overall complexity and leads a user to both understand what will
-be included at a glance and where it is located.
-.sp
-In addition Formulas should
-be used as often as possible.
+Before beginning this tutorial, ensure that the salt\-master is installed. To
+install the salt\-master, please review the installation documentation:
+\fI\%http://docs.saltstack.com/topics/installation/index.html\fP
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
-Formulas repositories on the saltstack\-formulas GitHub organization should
-not be pointed to directly from systems that automatically fetch new
-updates such as GitFS or similar tooling. Instead formulas repositories
-should be forked on GitHub or cloned locally, where unintended, automatic
-changes will not take place.
+Halite only works with Salt versions greater than 2014.1.0.
.UNINDENT
.UNINDENT
-.SS Structuring Pillar Files
+.SS Installing Halite Via Package
.sp
-Pillars are used to store
-secure and insecure data pertaining to minions. When designing the structure
-of the \fB/srv/pillar\fP directory, the pillars contained within
-should once again be focused on clear and concise data which users can easily
-review, modify, and understand.
-.sp
-The \fB/srv/pillar/\fP directory is primarily controlled by \fBtop.sls\fP\&. It
-should be noted that the pillar \fBtop.sls\fP is not used as a location to
-declare variables and their values. The \fBtop.sls\fP is used as a way to
-include other pillar files and organize the way they are matched based on
-environments or grains.
-.sp
-An example \fBtop.sls\fP may be as simple as the following:
-.sp
-/srv/pillar/top.sls:
+On CentOS, RHEL, or Fedora:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
-base:
- \(aq*\(aq:
- \- packages
+$ yum install python\-halite
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
-Any number of matchers can be added to the base environment. For example, here
-is an expanded version of the Pillar top file stated above:
+\fBNOTE:\fP
+.INDENT 0.0
+.INDENT 3.5
+By default python\-halite only installs CherryPy. If you would like to use
+a different webserver please review the instructions below to install
+pip and your server of choice. The package does not modify the master
+configuration with \fB/etc/salt/master\fP\&.
+.UNINDENT
+.UNINDENT
+.SS Installing Halite Using pip
.sp
-/srv/pillar/top.sls:
+To begin the installation of Halite from PyPI, you\(aqll need to install pip. The
+Salt package, as well as the bootstrap, do not install pip by default.
+.sp
+On CentOS, RHEL, or Fedora:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
-base:
- \(aq*\(aq:
- \- packages
- \(aqweb*\(aq:
- \- apache
- \- vim
+$ yum install python\-pip
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
-Or an even more complicated example, using a variety of matchers in numerous
-environments:
-.sp
-/srv/pillar/top.sls:
+On Debian:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
-base:
- \(aq*\(aq:
- \- apache
-dev:
- \(aqos:Debian\(aq:
- \- match: grain
- \- vim
-test:
- \(aq* and not G@os: Debian\(aq:
- \- match: compound
- \- emacs
+$ apt\-get install python\-pip
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
-It is clear to see through these examples how the top file provides users with
-power but when used incorrectly it can lead to confusing configurations. This
-is why it is important to understand that the top file for pillar is not used
-for variable definitions.
-.sp
-Each SLS file within the \fB/srv/pillar/\fP directory should correspond to the
-states which it matches.
-.sp
-This would mean that the \fBapache\fP pillar file should contain data relevant to
-Apache. Structuring files in this way once again ensures modularity, and
-creates a consistent understanding throughout our Salt environment. Users can
-expect that pillar variables found in an Apache state will live inside of an
-Apache pillar:
-.sp
-\fB/srv/pillar/apache.sls\fP:
+Once you have pip installed, use it to install halite:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
-apache:
- lookup:
- name: httpd
- config:
- tmpl: /etc/httpd/httpd.conf
+$ pip install \-U halite
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
-While this pillar file is simple, it shows how a pillar file explicitly
-relates to the state it is associated with.
-.SS Variable Flexibility
-.sp
-Salt allows users to define variables in SLS files. When creating a state
-variables should provide users with as much flexibility as possible. This
-means that variables should be clearly defined and easy to manipulate, and
-that sane defaults should exist in the event a variable is not properly
-defined. Looking at several examples shows how these different items can
-lead to extensive flexibility.
-.sp
-Although it is possible to set variables locally, this is generally not
-preferred:
-.sp
-\fB/srv/salt/apache/conf.sls\fP:
+Depending on the webserver you want to run halite through, you\(aqll need to
+install that piece as well. On RHEL based distros, use one of the following:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
-{% set name = \(aqhttpd\(aq %}
-{% set tmpl = \(aqsalt://apache/files/httpd.conf\(aq %}
+$ pip install cherrypy
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+$ pip install paste
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+$ yum install python\-devel
+$ yum install gcc
+$ pip install gevent
+$ pip install pyopenssl
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+On Debian based distributions:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+$ pip install CherryPy
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+$ pip install paste
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+$ apt\-get install gcc
+$ apt\-get install python\-dev
+$ apt\-get install libevent\-dev
+$ pip install gevent
+$ pip install pyopenssl
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.SS Configuring Halite Permissions
+.sp
+Configuring Halite access permissions is easy. By default, you only need to
+ensure that the @runner group is configured. In the \fB/etc/salt/master\fP file,
+uncomment and modify the following lines:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+external_auth:
+ pam:
+ testuser:
+ \- .*
+ \- \(aq@runner\(aq
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+\fBNOTE:\fP
+.INDENT 0.0
+.INDENT 3.5
+You cannot use the root user for pam login; it will fail to authenticate.
+.UNINDENT
+.UNINDENT
+.sp
+Halite uses the runner manage.present to get the status of minions, so runner
+permissions are required. For example:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+external_auth:
+ pam:
+ mytestuser:
+ \- .*
+ \- \(aq@runner\(aq
+ \- \(aq@wheel\(aq
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Currently Halite allows, but does not require, any wheel modules.
+.SS Configuring Halite Settings
+.sp
+Once you\(aqve configured the permissions for Halite, you\(aqll need to set up the
+Halite settings in the /etc/salt/master file. Halite supports CherryPy, Paste, and Gevent out of the box.
+.sp
+To configure cherrypy, add the following to the bottom of your /etc/salt/master file:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+halite:
+ level: \(aqdebug\(aq
+ server: \(aqcherrypy\(aq
+ host: \(aq0.0.0.0\(aq
+ port: \(aq8080\(aq
+ cors: False
+ tls: True
+ certpath: \(aq/etc/pki/tls/certs/localhost.crt\(aq
+ keypath: \(aq/etc/pki/tls/certs/localhost.key\(aq
+ pempath: \(aq/etc/pki/tls/certs/localhost.pem\(aq
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+If you wish to use paste:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+halite:
+ level: \(aqdebug\(aq
+ server: \(aqpaste\(aq
+ host: \(aq0.0.0.0\(aq
+ port: \(aq8080\(aq
+ cors: False
+ tls: True
+ certpath: \(aq/etc/pki/tls/certs/localhost.crt\(aq
+ keypath: \(aq/etc/pki/tls/certs/localhost.key\(aq
+ pempath: \(aq/etc/pki/tls/certs/localhost.pem\(aq
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+To use gevent:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+halite:
+ level: \(aqdebug\(aq
+ server: \(aqgevent\(aq
+ host: \(aq0.0.0.0\(aq
+ port: \(aq8080\(aq
+ cors: False
+ tls: True
+ certpath: \(aq/etc/pki/tls/certs/localhost.crt\(aq
+ keypath: \(aq/etc/pki/tls/certs/localhost.key\(aq
+ pempath: \(aq/etc/pki/tls/certs/localhost.pem\(aq
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+The "cherrypy" and "gevent" servers require the certpath and keypath files
+to run tls/ssl. The .crt file holds the public cert and the .key file holds
+the private key. Whereas the "paste" server requires a single .pem file that
+contains both the cert and key. This can be created simply by concatenating
+the .crt and .key files.
+.sp
+If you want to use a self\-signed cert, you can create one using the Salt.tls
+module:
+.sp
+\fBNOTE:\fP
+.INDENT 0.0
+.INDENT 3.5
+The following command needs to be run on your salt master.
+.UNINDENT
+.UNINDENT
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+salt\-call tls.create_self_signed_cert tls
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Note that certs generated by the above command can be found under the \fB/etc/pki/tls/certs/\fP directory.
+When using self\-signed certs, browsers will need approval before accepting the
+cert. If the web application page has been cached with a non\-HTTPS version of
+the app, then the browser cache will have to be cleared before it will
+recognize and prompt to accept the self\-signed certificate.
+.SS Starting Halite
+.sp
+Once you\(aqve configured the halite section of your /etc/salt/master, you can
+restart the salt\-master service, and your halite instance will be available.
+Depending on your configuration, the instance will be available either at
+\fI\%https://localhost:8080/app\fP, \fI\%https://domain:8080/app\fP, or
+\fI\%https://123.456.789.012:8080/app\fP .
+.sp
+\fBNOTE:\fP
+.INDENT 0.0
+.INDENT 3.5
+halite requires an HTML 5 compliant browser.
+.UNINDENT
+.UNINDENT
+.sp
+All logs relating to halite are logged to the default /var/log/salt/master file.
+.SS HTTP Modules
+.sp
+This tutorial demonstrates using the various HTTP modules available in Salt.
+These modules wrap the Python \fBtornado\fP, \fBurllib2\fP, and \fBrequests\fP
+libraries, extending them in a manner that is more consistent with Salt
+workflows.
+.SS The \fBsalt.utils.http\fP Library
+.sp
+This library forms the core of the HTTP modules. Since it is designed to be used
+from the minion as an execution module, in addition to the master as a runner,
+it was abstracted into this multi\-use library. This library can also be imported
+by 3rd\-party programs wishing to take advantage of its extended functionality.
+.sp
+Core functionality of the execution, state, and runner modules is derived from
+this library, so common usages between them are described here. Documentation
+specific to each module is described below.
+.sp
+This library can be imported with:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+import salt.utils.http
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.SS Configuring Libraries
+.sp
+This library can make use of either \fBtornado\fP, which is required by Salt,
+\fBurllib2\fP, which ships with Python, or \fBrequests\fP, which can be installed
+separately. By default, \fBtornado\fP will be used. In order to switch to
+\fBurllib2\fP, set the following variable:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+backend: urllib2
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+In order to switch to \fBrequests\fP, set the following variable:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+backend: requests
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+This can be set in the master or minion configuration file, or passed as an
+option directly to any \fBhttp.query()\fP functions.
+.SS \fBsalt.utils.http.query()\fP
+.sp
+This function forms a basic query, but with some add\-ons not present in the
+\fBtornado\fP, \fBurllib2\fP, and \fBrequests\fP libraries. Not all functionality
+currently available in these libraries has been added, but can be in future
+iterations.
+.SS HTTPS Request Methods
+.sp
+A basic query can be performed by calling this function with no more than a
+single URL:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+salt.utils.http.query(\(aqhttp://example.com\(aq)
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+By default the query will be performed with a \fBGET\fP method. The method can
+be overridden with the \fBmethod\fP argument:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+salt.utils.http.query(\(aqhttp://example.com/delete/url\(aq, \(aqDELETE\(aq)
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+When using the \fBPOST\fP method (and others, such as \fBPUT\fP), extra data is usually
+sent as well. This data can be sent directly, in whatever format is
+required by the remote server (XML, JSON, plain text, etc).
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+salt.utils.http.query(
+ \(aqhttp://example.com/delete/url\(aq,
+ method=\(aqPOST\(aq,
+ data=json.loads(mydict)
+)
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.SS Data Formatting and Templating
+.sp
+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):
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+salt.utils.http.query(
+ \(aqhttp://example.com/post/url\(aq,
+ method=\(aqPOST\(aq,
+ data_file=\(aq/srv/salt/somefile.xml\(aq
+)
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+To pass through a file that contains jinja + yaml templating (the default):
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+salt.utils.http.query(
+ \(aqhttp://example.com/post/url\(aq,
+ method=\(aqPOST\(aq,
+ data_file=\(aq/srv/salt/somefile.jinja\(aq,
+ data_render=True,
+ template_dict={\(aqkey1\(aq: \(aqvalue1\(aq, \(aqkey2\(aq: \(aqvalue2\(aq}
+)
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+To pass through a file that contains mako templating:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+salt.utils.http.query(
+ \(aqhttp://example.com/post/url\(aq,
+ method=\(aqPOST\(aq,
+ data_file=\(aq/srv/salt/somefile.mako\(aq,
+ data_render=True,
+ data_renderer=\(aqmako\(aq,
+ template_dict={\(aqkey1\(aq: \(aqvalue1\(aq, \(aqkey2\(aq: \(aqvalue2\(aq}
+)
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Because this function uses Salt\(aqs own rendering system, any Salt renderer can
+be used. Because Salt\(aqs renderer requires \fB__opts__\fP to be set, an \fBopts\fP
+dictionary should be passed in. If it is not, then the default \fB__opts__\fP
+values for the node type (master or minion) will be used. Because this library
+is intended primarily for use by minions, the default node type is \fBminion\fP\&.
+However, this can be changed to \fBmaster\fP if necessary.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+salt.utils.http.query(
+ \(aqhttp://example.com/post/url\(aq,
+ method=\(aqPOST\(aq,
+ data_file=\(aq/srv/salt/somefile.jinja\(aq,
+ data_render=True,
+ template_dict={\(aqkey1\(aq: \(aqvalue1\(aq, \(aqkey2\(aq: \(aqvalue2\(aq},
+ opts=__opts__
+)
-include:
- \- apache
-
-apache_conf:
- file.managed:
- \- name: {{ name }}
- \- source: {{ tmpl }}
- \- template: jinja
- \- user: root
- \- watch_in:
- \- service: apache
+salt.utils.http.query(
+ \(aqhttp://example.com/post/url\(aq,
+ method=\(aqPOST\(aq,
+ data_file=\(aq/srv/salt/somefile.jinja\(aq,
+ data_render=True,
+ template_dict={\(aqkey1\(aq: \(aqvalue1\(aq, \(aqkey2\(aq: \(aqvalue2\(aq},
+ node=\(aqmaster\(aq
+)
.ft P
.fi
.UNINDENT
.UNINDENT
+.SS Headers
.sp
-When generating this information it can be easily transitioned to the pillar
-where data can be overwritten, modified, and applied to multiple states, or
-locations within a single state:
-.sp
-\fB/srv/pillar/apache.sls\fP:
+Headers may also be passed through, either as a \fBheader_list\fP, a
+\fBheader_dict\fP, or as a \fBheader_file\fP\&. As with the \fBdata_file\fP, the
+\fBheader_file\fP may also be templated. Take note that because HTTP headers are
+normally syntactically\-correct YAML, they will automatically be imported as an
+a Python dict.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
-apache:
- lookup:
- name: httpd
- config:
- tmpl: salt://apache/files/httpd.conf
+salt.utils.http.query(
+ \(aqhttp://example.com/delete/url\(aq,
+ method=\(aqPOST\(aq,
+ header_file=\(aq/srv/salt/headers.jinja\(aq,
+ header_render=True,
+ header_renderer=\(aqjinja\(aq,
+ template_dict={\(aqkey1\(aq: \(aqvalue1\(aq, \(aqkey2\(aq: \(aqvalue2\(aq}
+)
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
-\fB/srv/salt/apache/conf.sls\fP:
+Because much of the data that would be templated between headers and data may be
+the same, the \fBtemplate_dict\fP is the same for both. Correcting possible
+variable name collisions is up to the user.
+.SS Authentication
+.sp
+The \fBquery()\fP function supports basic HTTP authentication. A username and
+password may be passed in as \fBusername\fP and \fBpassword\fP, respectively.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
-{% from "apache/map.jinja" import apache with context %}
-
-include:
- \- apache
-
-apache_conf:
- file.managed:
- \- name: {{ salt[\(aqpillar.get\(aq](\(aqapache:lookup:name\(aq) }}
- \- source: {{ salt[\(aqpillar.get\(aq](\(aqapache:lookup:config:tmpl\(aq) }}
- \- template: jinja
- \- user: root
- \- watch_in:
- \- service: apache
+salt.utils.http.query(
+ \(aqhttp://example.com\(aq,
+ username=\(aqlarry\(aq,
+ password=\(ga5700g3543v4r\(ga,
+)
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.SS Cookies and Sessions
+.sp
+Cookies are also supported, using Python\(aqs built\-in \fBcookielib\fP\&. However, they
+are turned off by default. To turn cookies on, set \fBcookies\fP to True.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+salt.utils.http.query(
+ \(aqhttp://example.com\(aq,
+ cookies=True
+)
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
-This flexibility provides users with a centralized location to modify
-variables, which is extremely important as an environment grows.
-.SS Modularity Within States
-.sp
-Ensuring that states are modular is one of the key concepts to understand
-within Salt. When creating a state a user must consider how many times the
-state could be re\-used, and what it relies on to operate. Below are several
-examples which will iteratively explain how a user can go from a state which
-is not very modular to one that is:
-.sp
-\fB/srv/salt/apache/init.sls\fP:
+By default cookies are stored in Salt\(aqs cache directory, normally
+\fB/var/cache/salt\fP, as a file called \fBcookies.txt\fP\&. However, this location
+may be changed with the \fBcookie_jar\fP argument:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
-httpd:
- pkg.installed: []
- service.running:
- \- enable: True
-
-/etc/httpd/httpd.conf:
- file.managed:
- \- source: salt://apache/files/httpd.conf
- \- template: jinja
- \- watch_in:
- \- service: httpd
+salt.utils.http.query(
+ \(aqhttp://example.com\(aq,
+ cookies=True,
+ cookie_jar=\(aq/path/to/cookie_jar.txt\(aq
+)
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
-The example above is probably the worst\-case scenario when writing a state.
-There is a clear lack of focus by naming both the pkg/service, and managed
-file directly as the state ID. This would lead to changing multiple requires
-within this state, as well as others that may depend upon the state.
-.sp
-Imagine if a require was used for the \fBhttpd\fP package in another state, and
-then suddenly it\(aqs a custom package. Now changes need to be made in multiple
-locations which increases the complexity and leads to a more error prone
-configuration.
-.sp
-There is also the issue of having the configuration file located in the init,
-as a user would be unable to simply install the service and use the default
-conf file.
-.sp
-Our second revision begins to address the referencing by using \fB\- name\fP, as
-opposed to direct ID references:
-.sp
-\fB/srv/salt/apache/init.sls\fP:
+By default, the format of the cookie jar is LWP (aka, lib\-www\-perl). This
+default was chosen because it is a human\-readable text file. If desired, the
+format of the cookie jar can be set to Mozilla:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
-apache:
- pkg.installed:
- \- name: httpd
- service.running:
- \- name: httpd
- \- enable: True
-
-apache_conf:
- file.managed:
- \- name: /etc/httpd/httpd.conf
- \- source: salt://apache/files/httpd.conf
- \- template: jinja
- \- watch_in:
- \- service: apache
+salt.utils.http.query(
+ \(aqhttp://example.com\(aq,
+ cookies=True,
+ cookie_jar=\(aq/path/to/cookie_jar.txt\(aq,
+ cookie_format=\(aqmozilla\(aq
+)
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
-The above init file is better than our original, yet it has several issues
-which lead to a lack of modularity. The first of these problems is the usage
-of static values for items such as the name of the service, the name of the
-managed file, and the source of the managed file. When these items are hard
-coded they become difficult to modify and the opportunity to make mistakes
-arises. It also leads to multiple edits that need to occur when changing
-these items (imagine if there were dozens of these occurrences throughout the
-state!). There is also still the concern of the configuration file data living
-in the same state as the service and package.
-.sp
-In the next example steps will be taken to begin addressing these issues.
-Starting with the addition of a map.jinja file (as noted in the
-Formula documentation), and
-modification of static values:
-.sp
-\fB/srv/salt/apache/map.jinja\fP:
+Because Salt commands are normally one\-off commands that are piped together,
+this library cannot normally behave as a normal browser, with session cookies
+that persist across multiple HTTP requests. However, the session can be
+persisted in a separate cookie jar. The default filename for this file, inside
+Salt\(aqs cache directory, is \fBcookies.session.p\fP\&. This can also be changed.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
-{% set apache = salt[\(aqgrains.filter_by\(aq]({
+salt.utils.http.query(
+ \(aqhttp://example.com\(aq,
+ persist_session=True,
+ session_cookie_jar=\(aq/path/to/jar.p\(aq
+)
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+The format of this file is msgpack, which is consistent with much of the rest
+of Salt\(aqs internal structure. Historically, the extension for this file is
+\fB\&.p\fP\&. There are no current plans to make this configurable.
+.SS Proxy
+.sp
+If the \fBtornado\fP backend is used (\fBtornado\fP is the default), proxy
+information configured in \fBproxy_host\fP, \fBproxy_port\fP, \fBproxy_username\fP,
+and \fBproxy_password\fP from the \fB__opts__\fP dictionary will be used. Normally
+these are set in the minion configuration file.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+proxy_host: proxy.my\-domain
+proxy_port: 31337
+proxy_username: charon
+proxy_password: obolus
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+salt.utils.http.query(
+ \(aqhttp://example.com\(aq,
+ opts=__opts__,
+ backend=\(aqtornado\(aq
+)
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.SS Return Data
+.sp
+\fBNOTE:\fP
+.INDENT 0.0
+.INDENT 3.5
+Return data encoding
+.sp
+If \fBdecode\fP is set to \fBTrue\fP, \fBquery()\fP will attempt to decode the
+return data. \fBdecode_type\fP defaults to \fBauto\fP\&. Set it to a specific
+encoding, \fBxml\fP, for example, to override autodetection.
+.UNINDENT
+.UNINDENT
+.sp
+Because Salt\(aqs http library was designed to be used with REST interfaces,
+\fBquery()\fP will attempt to decode the data received from the remote server
+when \fBdecode\fP is set to \fBTrue\fP\&. First it will check the \fBContent\-type\fP
+header to try and find references to XML. If it does not find any, it will look
+for references to JSON. If it does not find any, it will fall back to plain
+text, which will not be decoded.
+.sp
+JSON data is translated into a dict using Python\(aqs built\-in \fBjson\fP library.
+XML is translated using \fBsalt.utils.xml_util\fP, which will use Python\(aqs
+built\-in XML libraries to attempt to convert the XML into a dict. In order to
+force either JSON or XML decoding, the \fBdecode_type\fP may be set:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+salt.utils.http.query(
+ \(aqhttp://example.com\(aq,
+ decode_type=\(aqxml\(aq
+)
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Once translated, the return dict from \fBquery()\fP will include a dict called
+\fBdict\fP\&.
+.sp
+If the data is not to be translated using one of these methods, decoding may be
+turned off.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+salt.utils.http.query(
+ \(aqhttp://example.com\(aq,
+ decode=False
+)
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+If decoding is turned on, and references to JSON or XML cannot be found, then
+this module will default to plain text, and return the undecoded data as
+\fBtext\fP (even if text is set to \fBFalse\fP; see below).
+.sp
+The \fBquery()\fP function can return the HTTP status code, headers, and/or text
+as required. However, each must individually be turned on.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+salt.utils.http.query(
+ \(aqhttp://example.com\(aq,
+ status=True,
+ headers=True,
+ text=True
+)
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+The return from these will be found in the return dict as \fBstatus\fP,
+\fBheaders\fP and \fBtext\fP, respectively.
+.SS Writing Return Data to Files
+.sp
+It is possible to write either the return data or headers to files, as soon as
+the response is received from the server, but specifying file locations via the
+\fBtext_out\fP or \fBheaders_out\fP arguments. \fBtext\fP and \fBheaders\fP do not need
+to be returned to the user in order to do this.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+salt.utils.http.query(
+ \(aqhttp://example.com\(aq,
+ text=False,
+ headers=False,
+ text_out=\(aq/path/to/url_download.txt\(aq,
+ headers_out=\(aq/path/to/headers_download.txt\(aq,
+)
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.SS SSL Verification
+.sp
+By default, this function will verify SSL certificates. However, for testing or
+debugging purposes, SSL verification can be turned off.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+salt.utils.http.query(
+ \(aqhttps://example.com\(aq,
+ verify_ssl=False,
+)
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.SS CA Bundles
+.sp
+The \fBrequests\fP library has its own method of detecting which CA (certificate
+authority) bundle file to use. Usually this is implemented by the packager for
+the specific operating system distribution that you are using. However,
+\fBurllib2\fP requires a little more work under the hood. By default, Salt will
+try to auto\-detect the location of this file. However, if it is not in an
+expected location, or a different path needs to be specified, it may be done so
+using the \fBca_bundle\fP variable.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+salt.utils.http.query(
+ \(aqhttps://example.com\(aq,
+ ca_bundle=\(aq/path/to/ca_bundle.pem\(aq,
+)
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.SS Updating CA Bundles
+.sp
+The \fBupdate_ca_bundle()\fP function can be used to update the bundle file at a
+specified location. If the target location is not specified, then it will
+attempt to auto\-detect the location of the bundle file. If the URL to download
+the bundle from does not exist, a bundle will be downloaded from the cURL
+website.
+.sp
+CAUTION: The \fBtarget\fP and the \fBsource\fP should always be specified! Failure
+to specify the \fBtarget\fP may result in the file being written to the wrong
+location on the local system. Failure to specify the \fBsource\fP may cause the
+upstream URL to receive excess unnecessary traffic, and may cause a file to be
+download which is hazardous or does not meet the needs of the user.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+salt.utils.http.update_ca_bundle(
+ target=\(aq/path/to/ca\-bundle.crt\(aq,
+ source=\(aqhttps://example.com/path/to/ca\-bundle.crt\(aq,
+ opts=__opts__,
+)
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+The \fBopts\fP parameter should also always be specified. If it is, then the
+\fBtarget\fP and the \fBsource\fP may be specified in the relevant configuration
+file (master or minion) as \fBca_bundle\fP and \fBca_bundle_url\fP, respectively.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+ca_bundle: /path/to/ca\-bundle.crt
+ca_bundle_url: https://example.com/path/to/ca\-bundle.crt
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+If Salt is unable to auto\-detect the location of the CA bundle, it will raise
+an error.
+.sp
+The \fBupdate_ca_bundle()\fP function can also be passed a string or a list of
+strings which represent files on the local system, which should be appended (in
+the specified order) to the end of the CA bundle file. This is useful in
+environments where private certs need to be made available, and are not
+otherwise reasonable to add to the bundle file.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+salt.utils.http.update_ca_bundle(
+ opts=__opts__,
+ merge_files=[
+ \(aq/etc/ssl/private_cert_1.pem\(aq,
+ \(aq/etc/ssl/private_cert_2.pem\(aq,
+ \(aq/etc/ssl/private_cert_3.pem\(aq,
+ ]
+)
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.SS Test Mode
+.sp
+This function may be run in test mode. This mode will perform all work up until
+the actual HTTP request. By default, instead of performing the request, an empty
+dict will be returned. Using this function with \fBTRACE\fP logging turned on will
+reveal the contents of the headers and POST data to be sent.
+.sp
+Rather than returning an empty dict, an alternate \fBtest_url\fP may be passed in.
+If this is detected, then test mode will replace the \fBurl\fP with the
+\fBtest_url\fP, set \fBtest\fP to \fBTrue\fP in the return data, and perform the rest
+of the requested operations as usual. This allows a custom, non\-destructive URL
+to be used for testing when necessary.
+.SS Execution Module
+.sp
+The \fBhttp\fP execution module is a very thin wrapper around the
+\fBsalt.utils.http\fP library. The \fBopts\fP can be passed through as well, but if
+they are not specified, the minion defaults will be used as necessary.
+.sp
+Because passing complete data structures from the command line can be tricky at
+best and dangerous (in terms of execution injection attacks) at worse, the
+\fBdata_file\fP, and \fBheader_file\fP are likely to see more use here.
+.sp
+All methods for the library are available in the execution module, as kwargs.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+salt myminion http.query http://example.com/restapi method=POST \e
+ username=\(aqlarry\(aq password=\(aq5700g3543v4r\(aq headers=True text=True \e
+ status=True decode_type=xml data_render=True \e
+ header_file=/tmp/headers.txt data_file=/tmp/data.txt \e
+ header_render=True cookies=True persist_session=True
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.SS Runner Module
+.sp
+Like the execution module, the \fBhttp\fP runner module is a very thin wrapper
+around the \fBsalt.utils.http\fP library. The only significant difference is that
+because runners execute on the master instead of a minion, a target is not
+required, and default opts will be derived from the master config, rather than
+the minion config.
+.sp
+All methods for the library are available in the runner module, as kwargs.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+salt\-run http.query http://example.com/restapi method=POST \e
+ username=\(aqlarry\(aq password=\(aq5700g3543v4r\(aq headers=True text=True \e
+ status=True decode_type=xml data_render=True \e
+ header_file=/tmp/headers.txt data_file=/tmp/data.txt \e
+ header_render=True cookies=True persist_session=True
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.SS State Module
+.sp
+The state module is a wrapper around the runner module, which applies stateful
+logic to a query. All kwargs as listed above are specified as usual in state
+files, but two more kwargs are available to apply stateful logic. A required
+parameter is \fBmatch\fP, which specifies a pattern to look for in the return
+text. By default, this will perform a string comparison of looking for the
+value of match in the return text. In Python terms this looks like:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+if match in html_text:
+ return True
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+If more complex pattern matching is required, a regular expression can be used
+by specifying a \fBmatch_type\fP\&. By default this is set to \fBstring\fP, but it
+can be manually set to \fBpcre\fP instead. Please note that despite the name, this
+will use Python\(aqs \fBre.search()\fP rather than \fBre.match()\fP\&.
+.sp
+Therefore, the following states are valid:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+http://example.com/restapi:
+ http.query:
+ \- match: \(aqSUCCESS\(aq
+ \- username: \(aqlarry\(aq
+ \- password: \(aq5700g3543v4r\(aq
+ \- data_render: True
+ \- header_file: /tmp/headers.txt
+ \- data_file: /tmp/data.txt
+ \- header_render: True
+ \- cookies: True
+ \- persist_session: True
+
+http://example.com/restapi:
+ http.query:
+ \- match_type: pcre
+ \- match: \(aq(?i)succe[ss|ed]\(aq
+ \- username: \(aqlarry\(aq
+ \- password: \(aq5700g3543v4r\(aq
+ \- data_render: True
+ \- header_file: /tmp/headers.txt
+ \- data_file: /tmp/data.txt
+ \- header_render: True
+ \- cookies: True
+ \- persist_session: True
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+In addition to, or instead of a match pattern, the status code for a URL can be
+checked. This is done using the \fBstatus\fP argument:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+http://example.com/:
+ http.query:
+ \- status: \(aq200\(aq
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+If both are specified, both will be checked, but if only one is \fBTrue\fP and the
+other is \fBFalse\fP, then \fBFalse\fP will be returned. In this case, the comments
+in the return data will contain information for troubleshooting.
+.sp
+Because this is a monitoring state, it will return extra data to code that
+expects it. This data will always include \fBtext\fP and \fBstatus\fP\&. Optionally,
+\fBheaders\fP and \fBdict\fP may also be requested by setting the \fBheaders\fP and
+\fBdecode\fP arguments to True, respectively.
+.SS Using Salt at scale
+.sp
+The focus of this tutorial will be building a Salt infrastructure for handling
+large numbers of minions. This will include tuning, topology, and best practices.
+.sp
+For how to install the Salt Master please
+go here: \fI\%Installing saltstack\fP
+.sp
+\fBNOTE:\fP
+.INDENT 0.0
+.INDENT 3.5
+This tutorial is intended for large installations, although these same settings
+won\(aqt hurt, it may not be worth the complexity to smaller installations.
+.sp
+When used with minions, the term \(aqmany\(aq refers to at least a thousand
+and \(aqa few\(aq always means 500.
+.sp
+For simplicity reasons, this tutorial will default to the standard ports
+used by Salt.
+.UNINDENT
+.UNINDENT
+.SS The Master
+.sp
+The most common problems on the Salt Master are:
+.INDENT 0.0
+.IP 1. 3
+too many minions authing at once
+.IP 2. 3
+too many minions re\-authing at once
+.IP 3. 3
+too many minions re\-connecting at once
+.IP 4. 3
+too many minions returning at once
+.IP 5. 3
+too few resources (CPU/HDD)
+.UNINDENT
+.sp
+The first three are all "thundering herd" problems. To mitigate these issues
+we must configure the minions to back\-off appropriately when the Master is
+under heavy load.
+.sp
+The fourth is caused by masters with little hardware resources in combination
+with a possible bug in ZeroMQ. At least that\(aqs what it looks like till today
+(\fI\%Issue 118651\fP,
+\fI\%Issue 5948\fP,
+\fI\%Mail thread\fP)
+.sp
+To fully understand each problem, it is important to understand, how Salt works.
+.sp
+Very briefly, the Salt Master offers two services to the minions.
+.INDENT 0.0
+.IP \(bu 2
+a job publisher on port 4505
+.IP \(bu 2
+an open port 4506 to receive the minions returns
+.UNINDENT
+.sp
+All minions are always connected to the publisher on port 4505 and only connect
+to the open return port 4506 if necessary. On an idle Master, there will only
+be connections on port 4505.
+.SS Too many minions authing
+.sp
+When the Minion service is first started up, it will connect to its Master\(aqs publisher
+on port 4505. If too many minions are started at once, this can cause a "thundering herd".
+This can be avoided by not starting too many minions at once.
+.sp
+The connection itself usually isn\(aqt the culprit, the more likely cause of master\-side
+issues is the authentication that the Minion must do with the Master. If the Master
+is too heavily loaded to handle the auth request it will time it out. The Minion
+will then wait \fIacceptance_wait_time\fP to retry. If \fIacceptance_wait_time_max\fP is
+set then the Minion will increase its wait time by the \fIacceptance_wait_time\fP each
+subsequent retry until reaching \fIacceptance_wait_time_max\fP\&.
+.SS Too many minions re\-authing
+.sp
+This is most likely to happen in the testing phase of a Salt deployment, when
+all Minion keys have already been accepted, but the framework is being tested
+and parameters are frequently changed in the Salt Master\(aqs configuration
+file(s).
+.sp
+The Salt Master generates a new AES key to encrypt its publications at certain
+events such as a Master restart or the removal of a Minion key. If you are
+encountering this problem of too many minions re\-authing against the Master,
+you will need to recalibrate your setup to reduce the rate of events like a
+Master restart or Minion key removal (\fBsalt\-key \-d\fP).
+.sp
+When the Master generates a new AES key, the minions aren\(aqt notified of this
+but will discover it on the next pub job they receive. When the Minion
+receives such a job it will then re\-auth with the Master. Since Salt does
+minion\-side filtering this means that all the minions will re\-auth on the next
+command published on the master\-\- causing another "thundering herd". This can
+be avoided by setting the
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+random_reauth_delay: 60
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+in the minions configuration file to a higher value and stagger the amount
+of re\-auth attempts. Increasing this value will of course increase the time
+it takes until all minions are reachable via Salt commands.
+.SS Too many minions re\-connecting
+.sp
+By default the zmq socket will re\-connect every 100ms which for some larger
+installations may be too quick. This will control how quickly the TCP session is
+re\-established, but has no bearing on the auth load.
+.sp
+To tune the minions sockets reconnect attempts, there are a few values in
+the sample configuration file (default values)
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+recon_default: 1000
+recon_max: 5000
+recon_randomize: True
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.INDENT 0.0
+.IP \(bu 2
+recon_default: the default value the socket should use, i.e. 1000. This value is in
+milliseconds. (1000ms = 1 second)
+.IP \(bu 2
+recon_max: the max value that the socket should use as a delay before trying to reconnect
+This value is in milliseconds. (5000ms = 5 seconds)
+.IP \(bu 2
+recon_randomize: enables randomization between recon_default and recon_max
+.UNINDENT
+.sp
+To tune this values to an existing environment, a few decision have to be made.
+.INDENT 0.0
+.IP 1. 3
+How long can one wait, before the minions should be online and reachable via Salt?
+.IP 2. 3
+How many reconnects can the Master handle without a syn flood?
+.UNINDENT
+.sp
+These questions can not be answered generally. Their answers depend on the
+hardware and the administrators requirements.
+.sp
+Here is an example scenario with the goal, to have all minions reconnect
+within a 60 second time\-frame on a Salt Master service restart.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+recon_default: 1000
+recon_max: 59000
+recon_randomize: True
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Each Minion will have a randomized reconnect value between \(aqrecon_default\(aq
+and \(aqrecon_default + recon_max\(aq, which in this example means between 1000ms
+and 60000ms (or between 1 and 60 seconds). The generated random\-value will
+be doubled after each attempt to reconnect (ZeroMQ default behavior).
+.sp
+Lets say the generated random value is 11 seconds (or 11000ms).
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+reconnect 1: wait 11 seconds
+reconnect 2: wait 22 seconds
+reconnect 3: wait 33 seconds
+reconnect 4: wait 44 seconds
+reconnect 5: wait 55 seconds
+reconnect 6: wait time is bigger than 60 seconds (recon_default + recon_max)
+reconnect 7: wait 11 seconds
+reconnect 8: wait 22 seconds
+reconnect 9: wait 33 seconds
+reconnect x: etc.
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+With a thousand minions this will mean
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+1000/60 = ~16
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+round about 16 connection attempts a second. These values should be altered to
+values that match your environment. Keep in mind though, that it may grow over
+time and that more minions might raise the problem again.
+.SS Too many minions returning at once
+.sp
+This can also happen during the testing phase, if all minions are addressed at
+once with
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+$ salt * disk.usage
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+it may cause thousands of minions trying to return their data to the Salt Master
+open port 4506. Also causing a flood of syn\-flood if the Master can\(aqt handle that many
+returns at once.
+.sp
+This can be easily avoided with Salt\(aqs batch mode:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+$ salt * disk.usage \-b 50
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+This will only address 50 minions at once while looping through all addressed
+minions.
+.SS Too few resources
+.sp
+The masters resources always have to match the environment. There is no way
+to give good advise without knowing the environment the Master is supposed to
+run in. But here are some general tuning tips for different situations:
+.SS The Master is CPU bound
+.sp
+Salt uses RSA\-Key\-Pairs on the masters and minions end. Both generate 4096
+bit key\-pairs on first start. While the key\-size for the Master is currently
+not configurable, the minions keysize can be configured with different
+key\-sizes. For example with a 2048 bit key:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+keysize: 2048
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+With thousands of decryptions, the amount of time that can be saved on the
+masters end should not be neglected. See here for reference:
+\fI\%Pull Request 9235\fP how much
+influence the key\-size can have.
+.sp
+Downsizing the Salt Master\(aqs key is not that important, because the minions
+do not encrypt as many messages as the Master does.
+.sp
+In installations with large or with complex pillar files, it is possible
+for the master to exhibit poor performance as a result of having to render
+many pillar files at once. This exhibit itself in a number of ways, both
+as high load on the master and on minions which block on waiting for their
+pillar to be delivered to them.
+.sp
+To reduce pillar rendering times, it is possible to cache pillars on the
+master. To do this, see the set of master configuration options which
+are prefixed with \fIpillar_cache\fP\&.
+.sp
+\fBNOTE:\fP
+.INDENT 0.0
+.INDENT 3.5
+Caching pillars on the master may introduce security considerations.
+Be certain to read caveats outlined in the master configuration file
+to understand how pillar caching may affect a master\(aqs ability to
+protect sensitive data!
+.UNINDENT
+.UNINDENT
+.SS The Master is disk IO bound
+.sp
+By default, the Master saves every Minion\(aqs return for every job in its
+job\-cache. The cache can then be used later, to lookup results for previous
+jobs. The default directory for this is:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+cachedir: /var/cache/salt
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+and then in the \fB/proc\fP directory.
+.sp
+Each job return for every Minion is saved in a single file. Over time this
+directory can grow quite large, depending on the number of published jobs. The
+amount of files and directories will scale with the number of jobs published and
+the retention time defined by
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+keep_jobs: 24
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+250 jobs/day * 2000 minions returns = 500,000 files a day
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+If no job history is needed, the job cache can be disabled:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+job_cache: False
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+If the job cache is necessary there are (currently) 2 options:
+.INDENT 0.0
+.IP \(bu 2
+ext_job_cache: this will have the minions store their return data directly
+into a returner (not sent through the Master)
+.IP \(bu 2
+master_job_cache (New in \fI2014.7.0\fP): this will make the Master store the job
+data using a returner (instead of the local job cache on disk).
+.UNINDENT
+.sp
+If a master has many accepted keys, it may take a long time to publish a job
+because the master much first determine the matching minions and deliver
+that information back to the waiting client before the job can be published.
+.sp
+To mitigate this, a key cache may be enabled. This will reduce the load
+on the master to a single file open instead of thousands or tens of thousands.
+.sp
+This cache is updated by the maintanence process, however, which means that
+minions with keys that are accepted may not be targeted by the master
+for up to sixty seconds by default.
+.sp
+To enable the master key cache, set \fIkey_cache: \(aqsched\(aq\fP in the master
+configuration file.
+.SS How to Convert Jinja Logic to an Execution Module
+.SS The Problem: Jinja Gone Wild
+.sp
+It is often said in the Salt community that "Jinja is not a Programming Language".
+There\(aqs an even older saying known as Maslow\(aqs hammer.
+It goes something like
+"if all you have is a hammer, everything looks like a nail".
+Jinja is a reliable hammer, and so is the \fImaps.jinja\fP idiom.
+Unfortunately, it can lead to code that looks like the following.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+# storage/maps.yaml
+
+{% import_yaml \(aqstorage/defaults.yaml\(aq as default_settings %}
+{% set storage = default_settings.storage %}
+{% do storage.update(salt[\(aqgrains.filter_by\(aq]({
\(aqDebian\(aq: {
- \(aqserver\(aq: \(aqapache2\(aq,
- \(aqservice\(aq: \(aqapache2\(aq,
- \(aqconf\(aq: \(aq/etc/apache2/apache.conf\(aq,
},
\(aqRedHat\(aq: {
- \(aqserver\(aq: \(aqhttpd\(aq,
- \(aqservice\(aq: \(aqhttpd\(aq,
- \(aqconf\(aq: \(aq/etc/httpd/httpd.conf\(aq,
- },
-}, merge=salt[\(aqpillar.get\(aq](\(aqapache:lookup\(aq)) %}
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-/srv/pillar/apache.sls:
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-apache:
- lookup:
- config:
- tmpl: salt://apache/files/httpd.conf
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-\fB/srv/salt/apache/init.sls\fP:
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-{% from "apache/map.jinja" import apache with context %}
+ }
+}, merge=salt[\(aqpillar.get\(aq](\(aqstorage:lookup\(aq))) %}
-apache:
- pkg.installed:
- \- name: {{ apache.server }}
- service.running:
- \- name: {{ apache.service }}
- \- enable: True
+{% if \(aqVirtualBox\(aq == grains.get(\(aqvirtual\(aq, None) or \(aqoracle\(aq == grains.get(\(aqvirtual\(aq, None) %}
+{% do storage.update({\(aqdepot_ip\(aq: \(aq192.168.33.81\(aq, \(aqserver_ip\(aq: \(aq192.168.33.51\(aq}) %}
+{% else %}
+{% set colo = pillar.get(\(aqinventory\(aq, {}).get(\(aqcolo\(aq, \(aqUnknown\(aq) %}
+{% set servers_list = pillar.get(\(aqstorage_servers\(aq, {}).get(colo, [storage.depot_ip, ]) %}
+{% if opts.id.startswith(\(aqfoo\(aq) %}
+{% set modulus = servers_list | count %}
+{% set integer_id = opts.id | replace(\(aqfoo\(aq, \(aq\(aq) | int %}
+{% set server_index = integer_id % modulus %}
+{% else %}
+{% set server_index = 0 %}
+{% endif %}
+{% do storage.update({\(aqserver_ip\(aq: servers_list[server_index]}) %}
+{% endif %}
-apache_conf:
- file.managed:
- \- name: {{ apache.conf }}
- \- source: {{ salt[\(aqpillar.get\(aq](\(aqapache:lookup:config:tmpl\(aq) }}
- \- template: jinja
- \- user: root
- \- watch_in:
- \- service: apache
+{% for network, _ in salt.pillar.get(\(aqinventory:networks\(aq, {}) | dictsort %}
+{% do storage.ipsets.hash_net.foo_networks.append(network) %}
+{% endfor %}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
-The changes to this state now allow us to easily identify the location of the
-variables, as well as ensuring they are flexible and easy to modify.
-While this takes another step in the right direction, it is not yet complete.
-Suppose the user did not want to use the provided conf file, or even their own
-configuration file, but the default apache conf. With the current state setup
-this is not possible. To attain this level of modularity this state will need
-to be broken into two states.
+This is an example from the author\(aqs salt formulae demonstrating misuse of jinja.
+Aside from being difficult to read and maintain,
+accessing the logic it contains from a non\-jinja renderer
+while probably possible is a significant barrier!
+.SS Refactor
.sp
-\fB/srv/salt/apache/map.jinja\fP:
+The first step is to reduce the maps.jinja file to something reasonable.
+This gives us an idea of what the module we are writing needs to do.
+There is a lot of logic around selecting a storage server ip.
+Let\(aqs move that to an execution module.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
-{% set apache = salt[\(aqgrains.filter_by\(aq]({
+# storage/maps.yaml
+
+{% import_yaml \(aqstorage/defaults.yaml\(aq as default_settings %}
+{% set storage = default_settings.storage %}
+{% do storage.update(salt[\(aqgrains.filter_by\(aq]({
\(aqDebian\(aq: {
- \(aqserver\(aq: \(aqapache2\(aq,
- \(aqservice\(aq: \(aqapache2\(aq,
- \(aqconf\(aq: \(aq/etc/apache2/apache.conf\(aq,
},
\(aqRedHat\(aq: {
- \(aqserver\(aq: \(aqhttpd\(aq,
- \(aqservice\(aq: \(aqhttpd\(aq,
- \(aqconf\(aq: \(aq/etc/httpd/httpd.conf\(aq,
- },
-}, merge=salt[\(aqpillar.get\(aq](\(aqapache:lookup\(aq)) %}
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-\fB/srv/pillar/apache.sls\fP:
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-apache:
- lookup:
- config:
- tmpl: salt://apache/files/httpd.conf
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-\fB/srv/salt/apache/init.sls\fP:
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-{% from "apache/map.jinja" import apache with context %}
+ }
+}, merge=salt[\(aqpillar.get\(aq](\(aqstorage:lookup\(aq))) %}
-apache:
- pkg.installed:
- \- name: {{ apache.server }}
- service.running:
- \- name: {{ apache.service }}
- \- enable: True
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-\fB/srv/salt/apache/conf.sls\fP:
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-{% from "apache/map.jinja" import apache with context %}
+{% if \(aqVirtualBox\(aq == grains.get(\(aqvirtual\(aq, None) or \(aqoracle\(aq == grains.get(\(aqvirtual\(aq, None) %}
+{% do storage.update({\(aqdepot_ip\(aq: \(aq192.168.33.81\(aq}) %}
+{% endif %}
-include:
- \- apache
+{% do storage.update({\(aqserver_ip\(aq: salt[\(aqstorage.ip\(aq]()}) %}
-apache_conf:
- file.managed:
- \- name: {{ apache.conf }}
- \- source: {{ salt[\(aqpillar.get\(aq](\(aqapache:lookup:config:tmpl\(aq) }}
- \- template: jinja
- \- user: root
- \- watch_in:
- \- service: apache
+{% for network, _ in salt.pillar.get(\(aqinventory:networks\(aq, {}) | dictsort %}
+{% do storage.ipsets.hash_net.af_networks.append(network) %}
+{% endfor %}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
-This new structure now allows users to choose whether they only wish to
-install the default Apache, or if they wish, overwrite the default package,
-service, configuration file location, or the configuration file itself. In
-addition to this the data has been broken between multiple files allowing for
-users to identify where they need to change the associated data.
-.SS Storing Secure Data
-.sp
-Secure data refers to any information that you would not wish to share with
-anyone accessing a server. This could include data such as passwords,
-keys, or other information.
-.sp
-As all data within a state is accessible by EVERY server that is connected
-it is important to store secure data within pillar. This will ensure that only
-those servers which require this secure data have access to it. In this
-example a use can go from an insecure configuration to one which is only
-accessible by the appropriate hosts:
-.sp
-\fB/srv/salt/mysql/testerdb.sls\fP:
+And then, write the module.
+Note how the module encapsulates all of the logic around finding the storage server IP.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
-testdb:
- mysql_database.present:
- \- name: testerdb
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-\fB/srv/salt/mysql/user.sls\fP:
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-include:
- \- mysql.testerdb
+# _modules/storage.py
+#!python
-testdb_user:
- mysql_user.present:
- \- name: frank
- \- password: "test3rdb"
- \- host: localhost
- \- require:
- \- sls: mysql.testerdb
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-Many users would review this state and see that the password is there in plain
-text, which is quite problematic. It results in several issues which may not
-be immediately visible.
-.sp
-The first of these issues is clear to most users \-\- the password being visible
-in this state. This means that any minion will have a copy of this, and
-therefore the password which is a major security concern as minions may not
-be locked down as tightly as the master server.
-.sp
-The other issue that can be encountered is access by users on the master. If
-everyone has access to the states (or their repository), then they are able to
-review this password. Keeping your password data accessible by only a few
-users is critical for both security and peace of mind.
-.sp
-There is also the issue of portability. When a state is configured this way
-it results in multiple changes needing to be made. This was discussed in the
-sections above but it is a critical idea to drive home. If states are not
-portable it may result in more work later!
-.sp
-Fixing this issue is relatively simple, the content just needs to be moved to
-the associated pillar:
-.sp
-\fB/srv/pillar/mysql.sls\fP:
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-mysql:
- lookup:
- name: testerdb
- password: test3rdb
- user: frank
- host: localhost
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-\fB/srv/salt/mysql/testerdb.sls\fP:
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-testdb:
- mysql_database.present:
- \- name: {{ salt[\(aqpillar.get\(aq](\(aqmysql:lookup:name\(aq) }}
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-\fB/srv/salt/mysql/user.sls\fP:
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-include:
- \- mysql.testerdb
+\(aq\(aq\(aq
+Functions related to storage servers.
+\(aq\(aq\(aq
-testdb_user:
- mysql_user.present:
- \- name: {{ salt[\(aqpillar.get\(aq](\(aqmysql:lookup:user\(aq) }}
- \- password: {{ salt[\(aqpillar.get\(aq](\(aqmysql:lookup:password\(aq) }}
- \- host: {{ salt[\(aqpillar.get\(aq](\(aqmysql:lookup:host\(aq) }}
- \- require:
- \- sls: mysql.testerdb
+import re
+
+
+def ips():
+ \(aq\(aq\(aq
+ Provide a list of all local storage server IPs.
+
+ CLI Example::
+
+ salt \e* storage.ips
+ \(aq\(aq\(aq
+
+ if __grains__.get(\(aqvirtual\(aq, None) in [\(aqVirtualBox\(aq, \(aqoracle\(aq]:
+ return [\(aq192.168.33.51\(aq, ]
+
+ colo = __pillar__.get(\(aqinventory\(aq, {}).get(\(aqcolo\(aq, \(aqUnknown\(aq)
+ return __pillar__.get(\(aqstorage_servers\(aq, {}).get(colo, [\(aqunknown\(aq, ])
+
+
+def ip():
+ \(aq\(aq\(aq
+ Select and return a local storage server IP.
+
+ This loadbalances across storage servers by using the modulus of the client\(aqs id number.
+
+ :maintainer: Andrew Hammond
+ :maturity: new
+ :depends: None
+ :platform: all
+
+ CLI Example::
+
+ salt \e* storage.ip
+
+ \(aq\(aq\(aq
+
+ numerical_suffix = re.compile(r\(aq^.*(\ed+)$\(aq)
+ servers_list = ips()
+
+ m = numerical_suffix.match(__grains__[\(aqid\(aq])
+ if m:
+ modulus = len(servers_list)
+ server_number = int(m.group(1))
+ server_index = server_number % modulus
+ else:
+ server_index = 0
+
+ return servers_list[server_index]
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.SS Conclusion
+.sp
+That was... surprisingly straight\-forward.
+Now the logic is available in every renderer, instead of just Jinja.
+Best of all, it can be maintained in Python,
+which is a whole lot easier than Jinja.
+.SS LXC Management with Salt
+.sp
+\fBNOTE:\fP
+.INDENT 0.0
+.INDENT 3.5
+This walkthrough assumes basic knowledge of Salt. To get up to speed, check
+out the Salt Walkthrough\&.
+.UNINDENT
+.UNINDENT
+.SS Dependencies
+.sp
+Manipulation of LXC containers in Salt requires the minion to have an LXC
+version of at least 1.0 (an alpha or beta release of LXC 1.0 is acceptable).
+The following distributions are known to have new enough versions of LXC
+packaged:
+.INDENT 0.0
+.IP \(bu 2
+RHEL/CentOS 6 and later (via \fI\%EPEL\fP)
+.IP \(bu 2
+Fedora (All non\-EOL releases)
+.IP \(bu 2
+Debian 8.0 (Jessie)
+.IP \(bu 2
+Ubuntu 14.04 LTS and later (LXC templates are packaged separately as
+\fBlxc\-templates\fP, it is recommended to also install this package)
+.IP \(bu 2
+openSUSE 13.2 and later
+.UNINDENT
+.SS Profiles
+.sp
+Profiles allow for a sort of shorthand for commonly\-used
+configurations to be defined in the minion config file, grains, pillar, or the master config file. The
+profile is retrieved by Salt using the \fBconfig.get\fP function, which looks in those locations, in that
+order. This allows for profiles to be defined centrally in the master config
+file, with several options for overriding them (if necessary) on groups of
+minions or individual minions.
+.sp
+There are two types of profiles:
+.INDENT 0.0
+.INDENT 3.5
+.INDENT 0.0
+.IP \(bu 2
+One for defining the parameters used in container creation/clone.
+.IP \(bu 2
+One for defining the container\(aqs network interface(s) settings.
+.UNINDENT
+.UNINDENT
+.UNINDENT
+.SS Container Profiles
+.sp
+LXC container profiles are defined underneath the
+\fBlxc.container_profile\fP config option:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+lxc.container_profile:
+ centos:
+ template: centos
+ backing: lvm
+ vgname: vg1
+ lvname: lxclv
+ size: 10G
+ centos_big:
+ template: centos
+ backing: lvm
+ vgname: vg1
+ lvname: lxclv
+ size: 20G
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
-Now that the database details have been moved to the associated pillar file,
-only machines which are targeted via pillar will have access to these details.
-Access to users who should not be able to review these details can also be
-prevented while ensuring that they are still able to write states which take
-advantage of this information.
-.SH REMOTE EXECUTION
+Profiles are retrieved using the \fBconfig.get\fP
+function, with the \fBrecurse\fP merge strategy. This means that a profile can be
+defined at a lower level (for example, the master config file) and then parts
+of it can be overridden at a higher level (for example, in pillar data).
+Consider the following container profile data:
.sp
-Running pre\-defined or arbitrary commands on remote hosts, also known as
-remote execution, is the core function of Salt. The following links explore
-modules and returners, which are two key elements of remote execution.
-.sp
-\fBSalt Execution Modules\fP
-.sp
-Salt execution modules are called by the remote execution system to perform
-a wide variety of tasks. These modules provide functionality such as installing
-packages, restarting a service, running a remote command, transferring files,
-and so on.
+\fBIn the Master config file:\fP
.INDENT 0.0
.INDENT 3.5
-.INDENT 0.0
-.TP
-.B Full list of execution modules
-Contains: a list of core modules that ship with Salt.
-.TP
-.B Writing execution modules
-Contains: a guide on how to write Salt modules.
+.sp
+.nf
+.ft C
+lxc.container_profile:
+ centos:
+ template: centos
+ backing: lvm
+ vgname: vg1
+ lvname: lxclv
+ size: 10G
+.ft P
+.fi
.UNINDENT
.UNINDENT
+.sp
+\fBIn the Pillar data\fP
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+lxc.container_profile:
+ centos:
+ size: 20G
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Any minion with the above Pillar data would have the \fBsize\fP parameter in the
+\fBcentos\fP profile overridden to 20G, while those minions without the above
+Pillar data would have the 10G \fBsize\fP value. This is another way of achieving
+the same result as the \fBcentos_big\fP profile above, without having to define
+another whole profile that differs in just one value.
+.sp
+\fBNOTE:\fP
+.INDENT 0.0
+.INDENT 3.5
+In the 2014.7.x release cycle and earlier, container profiles are defined
+under \fBlxc.profile\fP\&. This parameter will still work in version 2015.5.0,
+but is deprecated and will be removed in a future release. Please note
+however that the profile merging feature described above will only work
+with profiles defined under \fBlxc.container_profile\fP, and only in versions
+2015.5.0 and later.
+.UNINDENT
+.UNINDENT
+.sp
+Additionally, in version 2015.5.0 container profiles have been expanded to
+support passing template\-specific CLI options to \fBlxc.create\fP\&. Below is a table describing the parameters which
+can be configured in container profiles:
+.TS
+center;
+|l|l|l|.
+_
+T{
+Parameter
+T} T{
+2015.5.0 and Newer
+T} T{
+2014.7.x and Earlier
+T}
+_
+T{
+\fItemplate\fP\s-2\u1\d\s0
+T} T{
+Yes
+T} T{
+Yes
+T}
+_
+T{
+\fIoptions\fP\s-2\u1\d\s0
+T} T{
+Yes
+T} T{
+No
+T}
+_
+T{
+\fIimage\fP\s-2\u1\d\s0
+T} T{
+Yes
+T} T{
+Yes
+T}
+_
+T{
+\fIbacking\fP
+T} T{
+Yes
+T} T{
+Yes
+T}
+_
+T{
+\fIsnapshot\fP\s-2\u2\d\s0
+T} T{
+Yes
+T} T{
+Yes
+T}
+_
+T{
+\fIlvname\fP\s-2\u1\d\s0
+T} T{
+Yes
+T} T{
+Yes
+T}
+_
+T{
+\fIfstype\fP\s-2\u1\d\s0
+T} T{
+Yes
+T} T{
+Yes
+T}
+_
+T{
+\fIsize\fP
+T} T{
+Yes
+T} T{
+Yes
+T}
+_
+.TE
+.INDENT 0.0
+.IP 1. 3
+Parameter is only supported for container creation, and will be ignored if
+the profile is used when cloning a container.
+.IP 2. 3
+Parameter is only supported for container cloning, and will be ignored if
+the profile is used when not cloning a container.
+.UNINDENT
+.SS Network Profiles
+.sp
+LXC network profiles are defined defined underneath the \fBlxc.network_profile\fP
+config option.
+By default, the module uses a DHCP based configuration and try to guess a bridge to
+get connectivity.
+.sp
+\fBWARNING:\fP
+.INDENT 0.0
+.INDENT 3.5
+on pre \fB2015.5.2\fP, you need to specify explicitly the network bridge
+.UNINDENT
+.UNINDENT
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+lxc.network_profile:
+ centos:
+ eth0:
+ link: br0
+ type: veth
+ flags: up
+ ubuntu:
+ eth0:
+ link: lxcbr0
+ type: veth
+ flags: up
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+As with container profiles, network profiles are retrieved using the
+\fBconfig.get\fP function, with the \fBrecurse\fP
+merge strategy. Consider the following network profile data:
+.sp
+\fBIn the Master config file:\fP
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+lxc.network_profile:
+ centos:
+ eth0:
+ link: br0
+ type: veth
+ flags: up
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+\fBIn the Pillar data\fP
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+lxc.network_profile:
+ centos:
+ eth0:
+ link: lxcbr0
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Any minion with the above Pillar data would use the \fBlxcbr0\fP interface as the
+bridge interface for any container configured using the \fBcentos\fP network
+profile, while those minions without the above Pillar data would use the
+\fBbr0\fP interface for the same.
+.sp
+\fBNOTE:\fP
+.INDENT 0.0
+.INDENT 3.5
+In the 2014.7.x release cycle and earlier, network profiles are defined
+under \fBlxc.nic\fP\&. This parameter will still work in version 2015.5.0, but
+is deprecated and will be removed in a future release. Please note however
+that the profile merging feature described above will only work with
+profiles defined under \fBlxc.network_profile\fP, and only in versions
+2015.5.0 and later.
+.UNINDENT
+.UNINDENT
+.sp
+The following are parameters which can be configured in network profiles. These
+will directly correspond to a parameter in an LXC configuration file (see \fBman
+5 lxc.container.conf\fP).
+.INDENT 0.0
+.IP \(bu 2
+\fBtype\fP \- Corresponds to \fBlxc.network.type\fP
+.IP \(bu 2
+\fBlink\fP \- Corresponds to \fBlxc.network.link\fP
+.IP \(bu 2
+\fBflags\fP \- Corresponds to \fBlxc.network.flags\fP
+.UNINDENT
+.sp
+Interface\-specific options (MAC address, IPv4/IPv6, etc.) must be passed on a
+container\-by\-container basis, for instance using the \fBnic_opts\fP argument to
+\fBlxc.create\fP:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+salt myminion lxc.create container1 profile=centos network_profile=centos nic_opts=\(aq{eth0: {ipv4: 10.0.0.20/24, gateway: 10.0.0.1}}\(aq
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+\fBWARNING:\fP
+.INDENT 0.0
+.INDENT 3.5
+The \fBipv4\fP, \fBipv6\fP, \fBgateway\fP, and \fBlink\fP (bridge) settings in
+network profiles / nic_opts will only work if the container doesn\(aqt redefine
+the network configuration (for example in
+\fB/etc/sysconfig/network\-scripts/ifcfg\-\fP on RHEL/CentOS,
+or \fB/etc/network/interfaces\fP on Debian/Ubuntu/etc.). Use these with
+caution. The container images installed using the \fBdownload\fP template,
+for instance, typically are configured for eth0 to use DHCP, which will
+conflict with static IP addresses set at the container level.
+.UNINDENT
+.UNINDENT
+.sp
+\fBNOTE:\fP
+.INDENT 0.0
+.INDENT 3.5
+For LXC < 1.0.7 and DHCP support, set \fBipv4.gateway: \(aqauto\(aq\fP is your
+network profile, ie.:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+lxc.network_profile.nic:
+ debian:
+ eth0:
+ link: lxcbr0
+ ipv4.gateway: \(aqauto\(aq
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.UNINDENT
+.UNINDENT
+.SS Old lxc support (<1.0.7)
+.sp
+With saltstack \fB2015.5.2\fP and above, normally the setting is autoselected, but
+before, you\(aqll need to teach your network profile to set
+\fBlxc.network.ipv4.gateway\fP to \fBauto\fP when using a classic ipv4 configuration.
+.sp
+Thus you\(aqll need
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+lxc.network_profile.foo:
+ etho:
+ link: lxcbr0
+ ipv4.gateway: auto
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.SS Tricky network setups Examples
+.sp
+This example covers how to make a container with both an internal ip and a
+public routable ip, wired on two veth pairs.
+.sp
+The another interface which receives directly a public routable ip can\(aqt be on
+the first interface that we reserve for private inter LXC networking.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+lxc.network_profile.foo:
+ eth0: {gateway: null, bridge: lxcbr0}
+ eth1:
+ # replace that by your main interface
+ \(aqlink\(aq: \(aqbr0\(aq
+ \(aqmac\(aq: \(aq00:16:5b:01:24:e1\(aq
+ \(aqgateway\(aq: \(aq2.20.9.14\(aq
+ \(aqipv4\(aq: \(aq2.20.9.1\(aq
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.SS Creating a Container on the CLI
+.SS From a Template
+.sp
+LXC is commonly distributed with several template scripts in
+/usr/share/lxc/templates. Some distros may package these separately in an
+\fBlxc\-templates\fP package, so make sure to check if this is the case.
+.sp
+There are LXC template scripts for several different operating systems, but
+some of them are designed to use tools specific to a given distribution. For
+instance, the \fBubuntu\fP template uses deb_bootstrap, the \fBcentos\fP template
+uses yum, etc., making these templates impractical when a container from a
+different OS is desired.
+.sp
+The \fBlxc.create\fP function is used to create
+containers using a template script. To create a CentOS container named
+\fBcontainer1\fP on a CentOS minion named \fBmycentosminion\fP, using the
+\fBcentos\fP LXC template, one can simply run the following command:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+salt mycentosminion lxc.create container1 template=centos
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+For these instances, there is a \fBdownload\fP template which retrieves minimal
+container images for several different operating systems. To use this template,
+it is necessary to provide an \fBoptions\fP parameter when creating the
+container, with three values:
+.INDENT 0.0
+.IP 1. 3
+\fBdist\fP \- the Linux distribution (i.e. \fBubuntu\fP or \fBcentos\fP)
+.IP 2. 3
+\fBrelease\fP \- the release name/version (i.e. \fBtrusty\fP or \fB6\fP)
+.IP 3. 3
+\fBarch\fP \- CPU architecture (i.e. \fBamd64\fP or \fBi386\fP)
+.UNINDENT
+.sp
+The \fBlxc.images\fP function (new in version
+2015.5.0) can be used to list the available images. Alternatively, the releases
+can be viewed on \fI\%http://images.linuxcontainers.org/images/\fP\&. The images are
+organized in such a way that the \fBdist\fP, \fBrelease\fP, and \fBarch\fP can be
+determined using the following URL format:
+\fBhttp://images.linuxcontainers.org/images/dist/release/arch\fP\&. For example,
+\fBhttp://images.linuxcontainers.org/images/centos/6/amd64\fP would correspond to
+a \fBdist\fP of \fBcentos\fP, a \fBrelease\fP of \fB6\fP, and an \fBarch\fP of \fBamd64\fP\&.
+.sp
+Therefore, to use the \fBdownload\fP template to create a new 64\-bit CentOS 6
+container, the following command can be used:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+salt myminion lxc.create container1 template=download options=\(aq{dist: centos, release: 6, arch: amd64}\(aq
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+\fBNOTE:\fP
+.INDENT 0.0
+.INDENT 3.5
+These command\-line options can be placed into a \fI\%container profile\fP, like so:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+lxc.container_profile.cent6:
+ template: download
+ options:
+ dist: centos
+ release: 6
+ arch: amd64
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+The \fBoptions\fP parameter is not supported in profiles for the 2014.7.x
+release cycle and earlier, so it would still need to be provided on the
+command\-line.
+.UNINDENT
+.UNINDENT
+.SS Cloning an Existing Container
+.sp
+To clone a container, use the \fBlxc.clone\fP
+function:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+salt myminion lxc.clone container2 orig=container1
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.SS Using a Container Image
+.sp
+While cloning is a good way to create new containers from a common base
+container, the source container that is being cloned needs to already exist on
+the minion. This makes deploying a common container across minions difficult.
+For this reason, Salt\(aqs \fBlxc.create\fP is capable
+of installing a container from a tar archive of another container\(aqs rootfs. To
+create an image of a container named \fBcent6\fP, run the following command as
+root:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+tar czf cent6.tar.gz \-C /var/lib/lxc/cent6 rootfs
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+\fBNOTE:\fP
+.INDENT 0.0
+.INDENT 3.5
+Before doing this, it is recommended that the container is stopped.
+.UNINDENT
+.UNINDENT
+.sp
+The resulting tarball can then be placed alongside the files in the salt
+fileserver and referenced using a \fBsalt://\fP URL. To create a container using
+an image, use the \fBimage\fP parameter with \fBlxc.create\fP:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+salt myminion lxc.create new\-cent6 image=salt://path/to/cent6.tar.gz
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+\fBNOTE:\fP
+.INDENT 0.0
+.INDENT 3.5
+Making images of containers with LVM backing
+.sp
+For containers with LVM backing, the rootfs is not mounted, so it is
+necessary to mount it first before creating the tar archive. When a
+container is created using LVM backing, an empty \fBrootfs\fP dir is handily
+created within \fB/var/lib/lxc/container_name\fP, so this can be used as the
+mountpoint. The location of the logical volume for the container will be
+\fB/dev/vgname/lvname\fP, where \fBvgname\fP is the name of the volume group,
+and \fBlvname\fP is the name of the logical volume. Therefore, assuming a
+volume group of \fBvg1\fP, a logical volume of \fBlxc\-cent6\fP, and a container
+name of \fBcent6\fP, the following commands can be used to create a tar
+archive of the rootfs:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+mount /dev/vg1/lxc\-cent6 /var/lib/lxc/cent6/rootfs
+tar czf cent6.tar.gz \-C /var/lib/lxc/cent6 rootfs
+umount /var/lib/lxc/cent6/rootfs
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.UNINDENT
+.UNINDENT
+.sp
+\fBWARNING:\fP
+.INDENT 0.0
+.INDENT 3.5
+One caveat of using this method of container creation is that
+\fB/etc/hosts\fP is left unmodified. This could cause confusion for some
+distros if salt\-minion is later installed on the container, as the
+functions that determine the hostname take \fB/etc/hosts\fP into account.
+.sp
+Additionally, when creating an rootfs image, be sure to remove
+\fB/etc/salt/minion_id\fP and make sure that \fBid\fP is not defined in
+\fB/etc/salt/minion\fP, as this will cause similar issues.
+.UNINDENT
+.UNINDENT
+.SS Initializing a New Container as a Salt Minion
+.sp
+The above examples illustrate a few ways to create containers on the CLI, but
+often it is desirable to also have the new container run as a Minion. To do
+this, the \fBlxc.init\fP function can be used. This
+function will do the following:
+.INDENT 0.0
+.IP 1. 3
+Create a new container
+.IP 2. 3
+Optionally set password and/or DNS
+.IP 3. 3
+Bootstrap the minion (using either \fI\%salt\-bootstrap\fP or a custom command)
+.UNINDENT
+.sp
+By default, the new container will be pointed at the same Salt Master as the
+host machine on which the container was created. It will then request to
+authenticate with the Master like any other bootstrapped Minion, at which point
+it can be accepted.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+salt myminion lxc.init test1 profile=centos
+salt\-key \-a test1
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+For even greater convenience, the \fBLXC runner\fP contains
+a runner function of the same name (\fBlxc.init\fP),
+which creates a keypair, seeds the new minion with it, and pre\-accepts the key,
+allowing for the new Minion to be created and authorized in a single step:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+salt\-run lxc.init test1 host=myminion profile=centos
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.SS Running Commands Within a Container
+.sp
+For containers which are not running their own Minion, commands can be run
+within the container in a manner similar to using (\fBcmd.run
+.pyx\fP so that
-the loader knows that the module needs to be imported as a Cython module. The
-compilation of the Cython module is automatic and happens when the minion
-starts, so only the \fB*.pyx\fP file is required.
-.SS Zip Archives as Modules
-.sp
-Python 2.3 and higher allows developers to directly import zip archives
-containing Python code. By setting \fBenable_zip_modules\fP to
-\fBTrue\fP in the minion config, the Salt loader will be able to import \fB\&.zip\fP
-files in this fashion. This allows Salt module developers to package
-dependencies with their modules for ease of deployment, isolation, etc.
-.sp
-For a user, Zip Archive modules behave just like other modules. When executing
-a function from a module provided as the file \fBmy_module.zip\fP, a user would
-call a function within that module as \fBmy_module.\fP\&.
-.SS Creating a Zip Archive Module
-.sp
-A Zip Archive module is structured similarly to a simple \fI\%Python package\fP\&.
-The \fB\&.zip\fP file contains a single directory with the same name as the module.
-The module code traditionally in \fB.py\fP goes in
-\fB/__init__.py\fP\&. The dependency packages are subdirectories of
-\fB/\fP\&.
-.sp
-Here is an example directory structure for the \fBlumberjack\fP module, which has
-two library dependencies (\fBsleep\fP and \fBwork\fP) to be included.
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-modules $ ls \-R lumberjack
-__init__.py sleep work
-
-lumberjack/sleep:
-__init__.py
-
-lumberjack/work:
-__init__.py
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-The contents of \fBlumberjack/__init__.py\fP show how to import and use these
-included libraries.
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-# Libraries included in lumberjack.zip
-from lumberjack import sleep, work
-
-
-def is_ok(person):
- \(aq\(aq\(aq Checks whether a person is really a lumberjack \(aq\(aq\(aq
- return sleep.all_night(person) and work.all_day(person)
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-Then, create the zip:
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-modules $ zip \-r lumberjack lumberjack
- adding: lumberjack/ (stored 0%)
- adding: lumberjack/__init__.py (deflated 39%)
- adding: lumberjack/sleep/ (stored 0%)
- adding: lumberjack/sleep/__init__.py (deflated 7%)
- adding: lumberjack/work/ (stored 0%)
- adding: lumberjack/work/__init__.py (deflated 7%)
-modules $ unzip \-l lumberjack.zip
-Archive: lumberjack.zip
- Length Date Time Name
- \-\-\-\-\-\-\-\- \-\-\-\- \-\-\-\- \-\-\-\-
- 0 08\-21\-15 20:08 lumberjack/
- 348 08\-21\-15 20:08 lumberjack/__init__.py
- 0 08\-21\-15 19:53 lumberjack/sleep/
- 83 08\-21\-15 19:53 lumberjack/sleep/__init__.py
- 0 08\-21\-15 19:53 lumberjack/work/
- 81 08\-21\-15 19:21 lumberjack/work/__init__.py
- \-\-\-\-\-\-\-\- \-\-\-\-\-\-\-
- 512 6 files
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-Once placed in \fBfile_roots\fP, Salt users can distribute and use
-\fBlumberjack.zip\fP like any other module.
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-$ sudo salt minion1 saltutil.sync_modules
-minion1:
- \- modules.lumberjack
-$ sudo salt minion1 lumberjack.is_ok \(aqMichael Palin\(aq
-minion1:
- True
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.SS Cross Calling Execution Modules
-.sp
-All of the Salt execution modules are available to each other and modules can
-call functions available in other execution modules.
-.sp
-The variable \fB__salt__\fP is packed into the modules after they are loaded into
-the Salt minion.
-.sp
-The \fB__salt__\fP variable is a \fI\%Python dictionary\fP
-containing all of the Salt functions. Dictionary keys are strings representing
-the names of the modules and the values are the functions themselves.
-.sp
-Salt modules can be cross\-called by accessing the value in the \fB__salt__\fP
-dict:
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-def foo(bar):
- return __salt__[\(aqcmd.run\(aq](bar)
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-This code will call the \fIrun\fP function in the \fBcmd\fP
-module and pass the argument \fBbar\fP to it.
-.SS Calling Execution Modules on the Salt Master
-.sp
-New in version 2016.11.0.
-
-.sp
-Execution modules can now also be called via the \fBsalt\-run\fP command
-using the salt runner\&.
-.SS Preloaded Execution Module Data
-.sp
-When interacting with execution modules often it is nice to be able to read
-information dynamically about the minion or to load in configuration parameters
-for a module.
-.sp
-Salt allows for different types of data to be loaded into the modules by the
-minion.
-.SS Grains Data
-.sp
-The values detected by the Salt Grains on the minion are available in a
-\fI\%dict\fP named \fB__grains__\fP and can be accessed
-from within callable objects in the Python modules.
-.sp
-To see the contents of the grains dictionary for a given system in your
-deployment run the \fBgrains.items()\fP function:
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-salt \(aqhostname\(aq grains.items \-\-output=pprint
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-Any value in a grains dictionary can be accessed as any other Python
-dictionary. For example, the grain representing the minion ID is stored in the
-\fBid\fP key and from an execution module, the value would be stored in
-\fB__grains__[\(aqid\(aq]\fP\&.
-.SS Module Configuration
-.sp
-Since parameters for configuring a module may be desired, Salt allows for
-configuration information from the minion configuration file to be passed to
-execution modules.
-.sp
-Since the minion configuration file is a YAML document, arbitrary configuration
-data can be passed in the minion config that is read by the modules. It is
-therefore \fBstrongly\fP recommended that the values passed in the configuration
-file match the module name. A value intended for the \fBtest\fP execution module
-should be named \fBtest.\fP\&.
-.sp
-The test execution module contains usage of the module configuration and the
-default configuration file for the minion contains the information and format
-used to pass data to the modules. \fBsalt.modules.test\fP,
-\fBconf/minion\fP\&.
-.SS Strings and Unicode
-.sp
-An execution module author should always assume that strings fed to the module
-have already decoded from strings into Unicode. In Python 2, these will
-be of type \(aqUnicode\(aq and in Python 3 they will be of type \fBstr\fP\&. Calling
-from a state to other Salt sub\-systems, should pass Unicode (or bytes if passing binary data). In the
-rare event that a state needs to write directly to disk, Unicode should be
-encoded to a string immediately before writing to disk. An author may use
-\fB__salt_system_encoding__\fP to learn what the encoding type of the system is.
-For example, \fI\(aqmy_string\(aq.encode(__salt_system_encoding__\(aq)\fP\&.
-.SS Outputter Configuration
-.sp
-Since execution module functions can return different data, and the way the
-data is printed can greatly change the presentation, Salt allows for a specific
-outputter to be set on a function\-by\-function basis.
-.sp
-This is done be declaring an \fB__outputter__\fP dictionary in the global scope
-of the module. The \fB__outputter__\fP dictionary contains a mapping of function
-names to Salt outputters\&.
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-__outputter__ = {
- \(aqrun\(aq: \(aqtxt\(aq
-}
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-This will ensure that the \fBtxt\fP outputter is used to display output from the
-\fBrun\fP function.
-.SS Virtual Modules
-.sp
-Virtual modules let you override the name of a module in order to use the same
-name to refer to one of several similar modules. The specific module that is
-loaded for a virtual name is selected based on the current platform or
-environment.
-.sp
-For example, packages are managed across platforms using the \fBpkg\fP module.
-\fBpkg\fP is a virtual module name that is an alias for the specific package
-manager module that is loaded on a specific system (for example, \fByumpkg\fP on RHEL/CentOS systems , and \fBaptpkg\fP on Ubuntu).
-.sp
-Virtual module names are set using the \fB__virtual__\fP function and the
-\fI\%virtual name\fP\&.
-.SS \fB__virtual__\fP Function
-.sp
-The \fB__virtual__\fP function returns either a \fI\%string\fP,
-\fI\%True\fP, \fI\%False\fP, or \fI\%False\fP with an \fI\%error
-string\fP\&. If a string is returned then the module is loaded
-using the name of the string as the virtual name. If \fBTrue\fP is returned the
-module is loaded using the current module name. If \fBFalse\fP is returned the
-module is not loaded. \fBFalse\fP lets the module perform system checks and
-prevent loading if dependencies are not met.
-.sp
-Since \fB__virtual__\fP is called before the module is loaded, \fB__salt__\fP will
-be unavailable as it will not have been packed into the module at this point in
-time.
+As of Salt 0.16.0, the ability to connect minions to multiple masters has been
+made available. The multi\-master system allows for redundancy of Salt
+masters and facilitates multiple points of communication out to minions. When
+using a multi\-master setup, all masters are running hot, and any active master
+can be used to send commands out to the minions.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
-Modules which return a string from \fB__virtual__\fP that is already used by
-a module that ships with Salt will _override_ the stock module.
+If you need failover capabilities with multiple masters, there is also a
+MultiMaster\-PKI setup available, that uses a different topology
+\fI\%MultiMaster\-PKI with Failover Tutorial\fP
.UNINDENT
.UNINDENT
-.SS Returning Error Information from \fB__virtual__\fP
.sp
-Optionally, Salt plugin modules, such as execution, state, returner, beacon,
-etc. modules may additionally return a string containing the reason that a
-module could not be loaded. For example, an execution module called \fBcheese\fP
-and a corresponding state module also called \fBcheese\fP, both depending on a
-utility called \fBenzymes\fP should have \fB__virtual__\fP functions that handle
-the case when the dependency is unavailable.
+In 0.16.0, the masters do not share any information, keys need to be accepted
+on both masters, and shared files need to be shared manually or use tools like
+the git fileserver backend to ensure that the \fBfile_roots\fP are
+kept consistent.
+.sp
+Beginning with Salt 2016.11.0, the Pluggable Minion Data Cache
+was introduced. The minion data cache contains the Salt Mine data, minion grains, and minion
+pillar information cached on the Salt Master. By default, Salt uses the \fBlocalfs\fP cache
+module, but other external data stores can be used instead.
+.sp
+Using a pluggable minion cache modules allows for the data stored on a Salt Master about
+Salt Minions to be replicated on other Salt Masters the Minion is connected to. Please see
+the Minion Data Cache documentation for more information and configuration
+examples.
+.SS Summary of Steps
.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-\(aq\(aq\(aq
-Cheese execution (or returner/beacon/etc.) module
-\(aq\(aq\(aq
-try:
- import enzymes
- HAS_ENZYMES = True
-except ImportError:
- HAS_ENZYMES = False
-
-
-def __virtual__():
- \(aq\(aq\(aq
- only load cheese if enzymes are available
- \(aq\(aq\(aq
- if HAS_ENZYMES:
- return \(aqcheese\(aq
- else:
- return False, \(aqThe cheese execution module cannot be loaded: enzymes unavailable.\(aq
-.ft P
-.fi
+.IP 1. 3
+Create a redundant master server
+.IP 2. 3
+Copy primary master key to redundant master
+.IP 3. 3
+Start redundant master
+.IP 4. 3
+Configure minions to connect to redundant master
+.IP 5. 3
+Restart minions
+.IP 6. 3
+Accept keys on redundant master
.UNINDENT
-.UNINDENT
-.INDENT 0.0
-.INDENT 3.5
+.SS Prepping a Redundant Master
.sp
-.nf
-.ft C
-\(aq\(aq\(aq
-Cheese state module
-\(aq\(aq\(aq
-
-def __virtual__():
- \(aq\(aq\(aq
- only load cheese if enzymes are available
- \(aq\(aq\(aq
- # predicate loading of the cheese state on the corresponding execution module
- if \(aqcheese.slice\(aq in __salt__:
- return \(aqcheese\(aq
- else:
- return False, \(aqThe cheese state module cannot be loaded: enzymes unavailable.\(aq
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.SS Examples
-.sp
-The package manager modules are among the best examples of using the
-\fB__virtual__\fP function. A table of all the virtual \fBpkg\fP modules can be
-found here\&.
-.SS Overriding Virtual Module Providers
-.sp
-Salt often uses OS grains (\fBos\fP, \fBosrelease\fP, \fBos_family\fP, etc.) to
-determine which module should be loaded as the virtual module for \fBpkg\fP,
-\fBservice\fP, etc. Sometimes this OS detection is incomplete, with new distros
-popping up, existing distros changing init systems, etc. The virtual modules
-likely to be affected by this are in the list below (click each item for more
-information):
-.INDENT 0.0
-.IP \(bu 2
-pkg
-.IP \(bu 2
-service
-.IP \(bu 2
-user
-.IP \(bu 2
-shadow
-.IP \(bu 2
-group
-.UNINDENT
-.sp
-If Salt is using the wrong module for one of these, first of all, please
-\fI\%report it on the issue tracker\fP, so that this issue can be resolved for a
-future release. To make it easier to troubleshoot, please also provide the
-\fBgrains.items\fP output, taking care to
-redact any sensitive information.
-.sp
-Then, while waiting for the SaltStack development team to fix the issue, Salt
-can be made to use the correct module using the \fBproviders\fP option
-in the minion config file:
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-providers:
- service: systemd
- pkg: aptpkg
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-The above example will force the minion to use the \fBsystemd\fP module to provide service management, and the
-\fBaptpkg\fP module to provide package management.
-.SS Logging Restrictions
-.sp
-As a rule, logging should not be done anywhere in a Salt module before it is
-loaded. This rule apples to all code that would run before the \fB__virtual__()\fP
-function, as well as the code within the \fB__virtual__()\fP function itself.
-.sp
-If logging statements are made before the virtual function determines if
-the module should be loaded, then those logging statements will be called
-repeatedly. This clutters up log files unnecessarily.
-.sp
-Exceptions may be considered for logging statements made at the \fBtrace\fP level.
-However, it is better to provide the necessary information by another means.
-One method is to \fI\%return error information\fP in the
-\fB__virtual__()\fP function.
-.SS \fB__virtualname__\fP
-.sp
-\fB__virtualname__\fP is a variable that is used by the documentation build
-system to know the virtual name of a module without calling the \fB__virtual__\fP
-function. Modules that return a string from the \fB__virtual__\fP function
-must also set the \fB__virtualname__\fP variable.
-.sp
-To avoid setting the virtual name string twice, you can implement
-\fB__virtual__\fP to return the value set for \fB__virtualname__\fP using a pattern
-similar to the following:
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-# Define the module\(aqs virtual name
-__virtualname__ = \(aqpkg\(aq
-
-
-def __virtual__():
- \(aq\(aq\(aq
- Confine this module to Mac OS with Homebrew.
- \(aq\(aq\(aq
-
- if salt.utils.which(\(aqbrew\(aq) and __grains__[\(aqos\(aq] == \(aqMacOS\(aq:
- return __virtualname__
- return False
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-The \fB__virtual__()\fP function can return a \fBTrue\fP or \fBFalse\fP boolean, a tuple,
-or a string. If it returns a \fBTrue\fP value, this \fB__virtualname__\fP module\-level
-attribute can be set as seen in the above example. This is the string that the module
-should be referred to as.
-.sp
-When \fB__virtual__()\fP returns a tuple, the first item should be a boolean and the
-second should be a string. This is typically done when the module should not load. The
-first value of the tuple is \fBFalse\fP and the second is the error message to display
-for why the module did not load.
-.sp
-For example:
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-def __virtual__():
- \(aq\(aq\(aq
- Only load if git exists on the system
- \(aq\(aq\(aq
- if salt.utils.which(\(aqgit\(aq) is None:
- return (False,
- \(aqThe git execution module cannot be loaded: git unavailable.\(aq)
- else:
- return True
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.SS Documentation
-.sp
-Salt execution modules are documented. The \fBsys.doc()\fP function will return
-the documentation for all available modules:
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-salt \(aq*\(aq sys.doc
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-The \fBsys.doc\fP function simply prints out the docstrings found in the modules;
-when writing Salt execution modules, please follow the formatting conventions
-for docstrings as they appear in the other modules.
-.SS Adding Documentation to Salt Modules
-.sp
-It is strongly suggested that all Salt modules have documentation added.
-.sp
-To add documentation add a \fI\%Python docstring\fP to the function.
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-def spam(eggs):
- \(aq\(aq\(aq
- A function to make some spam with eggs!
-
- CLI Example::
-
- salt \(aq*\(aq test.spam eggs
- \(aq\(aq\(aq
- return eggs
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-Now when the sys.doc call is executed the docstring will be cleanly returned
-to the calling terminal.
-.sp
-Documentation added to execution modules in docstrings will automatically be
-added to the online web\-based documentation.
-.SS Add Execution Module Metadata
-.sp
-When writing a Python docstring for an execution module, add information about
-the module using the following field lists:
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-:maintainer: Thomas Hatch
-:maturity: new
-:depends: python\-mysqldb
-:platform: all
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-The maintainer field is a comma\-delimited list of developers who help maintain
-this module.
-.sp
-The maturity field indicates the level of quality and testing for this module.
-Standard labels will be determined.
-.sp
-The depends field is a comma\-delimited list of modules that this module depends
-on.
-.sp
-The platform field is a comma\-delimited list of platforms that this module is
-known to run on.
-.SS Log Output
-.sp
-You can call the logger from custom modules to write messages to the minion
-logs. The following code snippet demonstrates writing log messages:
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-import logging
-
-log = logging.getLogger(__name__)
-
-log.info(\(aqHere is Some Information\(aq)
-log.warning(\(aqYou Should Not Do That\(aq)
-log.error(\(aqIt Is Busted\(aq)
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.SS Aliasing Functions
-.sp
-Sometimes one wishes to use a function name that would shadow a python built\-in.
-A common example would be \fBset()\fP\&. To support this, append an underscore to
-the function definition, \fBdef set_():\fP, and use the \fB__func_alias__\fP feature
-to provide an alias to the function.
-.sp
-\fB__func_alias__\fP is a dictionary where each key is the name of a function in
-the module, and each value is a string representing the alias for that function.
-When calling an aliased function from a different execution module, state
-module, or from the cli, the alias name should be used.
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-__func_alias__ = {
- \(aqset_\(aq: \(aqset\(aq,
- \(aqlist_\(aq: \(aqlist\(aq,
-}
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.SS Private Functions
-.sp
-In Salt, Python callable objects contained within an execution module are made
-available to the Salt minion for use. The only exception to this rule is a
-callable object with a name starting with an underscore \fB_\fP\&.
-.SS Objects Loaded Into the Salt Minion
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-def foo(bar):
- return bar
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.SS Objects NOT Loaded into the Salt Minion
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-def _foobar(baz): # Preceded with an _
- return baz
-
-cheese = {} # Not a callable Python object
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.SS Useful Decorators for Modules
-.SS Depends Decorator
-.sp
-When writing execution modules there are many times where some of the module
-will work on all hosts but some functions have an external dependency, such as
-a service that needs to be installed or a binary that needs to be present on
-the system.
-.sp
-Instead of trying to wrap much of the code in large try/except blocks, a
-decorator can be used.
-.sp
-If the dependencies passed to the decorator don\(aqt exist, then the salt minion
-will remove those functions from the module on that host.
-.sp
-If a \fBfallback_function\fP is defined, it will replace the function instead of
-removing it
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-import logging
-
-from salt.utils.decorators import depends
-
-log = logging.getLogger(__name__)
-
-try:
- import dependency_that_sometimes_exists
-except ImportError as e:
- log.trace(\(aqFailed to import dependency_that_sometimes_exists: {0}\(aq.format(e))
-
-@depends(\(aqdependency_that_sometimes_exists\(aq)
-def foo():
- \(aq\(aq\(aq
- Function with a dependency on the "dependency_that_sometimes_exists" module,
- if the "dependency_that_sometimes_exists" is missing this function will not exist
- \(aq\(aq\(aq
- return True
-
-def _fallback():
- \(aq\(aq\(aq
- Fallback function for the depends decorator to replace a function with
- \(aq\(aq\(aq
- return \(aq"dependency_that_sometimes_exists" needs to be installed for this function to exist\(aq
-
-@depends(\(aqdependency_that_sometimes_exists\(aq, fallback_function=_fallback)
-def foo():
- \(aq\(aq\(aq
- Function with a dependency on the "dependency_that_sometimes_exists" module.
- If the "dependency_that_sometimes_exists" is missing this function will be
- replaced with "_fallback"
- \(aq\(aq\(aq
- return True
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-In addition to global dependencies the depends decorator also supports raw
-booleans.
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-from salt.utils.decorators import depends
-
-HAS_DEP = False
-try:
- import dependency_that_sometimes_exists
- HAS_DEP = True
-except ImportError:
- pass
-
-@depends(HAS_DEP)
-def foo():
- return True
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.SH CONFIGURATION MANAGEMENT
-.sp
-Salt contains a robust and flexible configuration management framework, which
-is built on the remote execution core. This framework executes on the minions,
-allowing effortless, simultaneous configuration of tens of thousands of hosts,
-by rendering language specific state files. The following links provide
-resources to learn more about state and renderers.
-.INDENT 0.0
-.TP
-\fBStates\fP
-Express the state of a host using small, easy to read, easy to
-understand configuration files. \fINo programming required\fP\&.
-.INDENT 7.0
-.TP
-.B Full list of states
-Contains: list of install packages, create users, transfer files, start
-services, and so on.
-.TP
-.B Pillar System
-Contains: description of Salt\(aqs Pillar system.
-.TP
-.B Highstate data structure
-Contains: a dry vocabulary and technical representation of the
-configuration format that states represent.
-.TP
-.B Writing states
-Contains: a guide on how to write Salt state modules, easily extending
-Salt to directly manage more software.
-.UNINDENT
-.UNINDENT
+The first task is to prepare the redundant master. If the redundant master is
+already running, stop it. There is only one requirement when preparing a
+redundant master, which is that masters share the same private key. When the
+first master was created, the master\(aqs identifying key pair was generated and
+placed in the master\(aqs \fBpki_dir\fP\&. The default location of the master\(aqs key
+pair is \fB/etc/salt/pki/master/\fP\&. Take the private key, \fBmaster.pem\fP, and
+copy it to the same location on the redundant master. Do the same for the
+master\(aqs public key, \fBmaster.pub\fP\&. Assuming that no minions have yet been
+connected to the new redundant master, it is safe to delete any existing key
+in this location and replace it.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
-Salt execution modules are different from state modules and cannot be
-called as a state in an SLS file. In other words, this will not work:
+There is no logical limit to the number of redundant masters that can be
+used.
+.UNINDENT
+.UNINDENT
+.sp
+Once the new key is in place, the redundant master can be safely started.
+.SS Configure Minions
+.sp
+Since minions need to be master\-aware, the new master needs to be added to the
+minion configurations. Simply update the minion configurations to list all
+connected masters:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
-moe:
- user.rename:
- \- new_name: larry
- \- onlyif: id moe
+master:
+ \- saltmaster1.example.com
+ \- saltmaster2.example.com
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
-You must use the \fBmodule\fP states to call
-execution modules directly. Here\(aqs an example:
+Now the minion can be safely restarted.
+.sp
+\fBNOTE:\fP
+.INDENT 0.0
+.INDENT 3.5
+If the ipc_mode for the minion is set to TCP (default in Windows), then
+each minion in the multi\-minion setup (one per master) needs its own
+tcp_pub_port and tcp_pull_port.
+.sp
+If these settings are left as the default 4510/4511, each minion object
+will receive a port 2 higher than the previous. Thus the first minion will
+get 4510/4511, the second will get 4512/4513, and so on. If these port
+decisions are unacceptable, you must configure tcp_pub_port and
+tcp_pull_port with lists of ports for each master. The length of these
+lists should match the number of masters, and there should not be overlap
+in the lists.
+.UNINDENT
+.UNINDENT
+.sp
+Now the minions will check into the original master and also check into the new
+redundant master. Both masters are first\-class and have rights to the minions.
+.sp
+\fBNOTE:\fP
+.INDENT 0.0
+.INDENT 3.5
+Minions can automatically detect failed masters and attempt to reconnect
+to reconnect to them quickly. To enable this functionality, set
+\fImaster_alive_interval\fP in the minion config and specify a number of
+seconds to poll the masters for connection status.
+.sp
+If this option is not set, minions will still reconnect to failed masters
+but the first command sent after a master comes back up may be lost while
+the minion authenticates.
+.UNINDENT
+.UNINDENT
+.SS Sharing Files Between Masters
+.sp
+Salt does not automatically share files between multiple masters. A number of
+files should be shared or sharing of these files should be strongly considered.
+.SS Minion Keys
+.sp
+Minion keys can be accepted the normal way using \fBsalt\-key\fP on both
+masters. Keys accepted, deleted, or rejected on one master will NOT be
+automatically managed on redundant masters; this needs to be taken care of by
+running salt\-key on both masters or sharing the
+\fB/etc/salt/pki/master/{minions,minions_pre,minions_rejected}\fP directories
+between masters.
+.sp
+\fBNOTE:\fP
+.INDENT 0.0
+.INDENT 3.5
+While sharing the \fB/etc/salt/pki/master\fP directory will work, it is
+strongly discouraged, since allowing access to the \fBmaster.pem\fP key
+outside of Salt creates a \fISERIOUS\fP security risk.
+.UNINDENT
+.UNINDENT
+.SS File_Roots
+.sp
+The \fBfile_roots\fP contents should be kept consistent between
+masters. Otherwise state runs will not always be consistent on minions since
+instructions managed by one master will not agree with other masters.
+.sp
+The recommended way to sync these is to use a fileserver backend like gitfs or
+to keep these files on shared storage.
+.sp
+\fBIMPORTANT:\fP
+.INDENT 0.0
+.INDENT 3.5
+If using gitfs/git_pillar with the cachedir shared between masters using
+\fI\%GlusterFS\fP, nfs, or another network filesystem, and the masters are
+running Salt 2015.5.9 or later, it is strongly recommended not to turn off
+\fBgitfs_global_lock\fP/\fBgit_pillar_global_lock\fP as
+doing so will cause lock files to be removed if they were created by a
+different master.
+.UNINDENT
+.UNINDENT
+.SS Pillar_Roots
+.sp
+Pillar roots should be given the same considerations as
+\fBfile_roots\fP\&.
+.SS Master Configurations
+.sp
+While reasons may exist to maintain separate master configurations, it is wise
+to remember that each master maintains independent control over minions.
+Therefore, access controls should be in sync between masters unless a valid
+reason otherwise exists to keep them inconsistent.
+.sp
+These access control options include but are not limited to:
+.INDENT 0.0
+.IP \(bu 2
+external_auth
+.IP \(bu 2
+publisher_acl
+.IP \(bu 2
+peer
+.IP \(bu 2
+peer_run
+.UNINDENT
+.SS Multi\-Master\-PKI Tutorial With Failover
+.sp
+This tutorial will explain, how to run a salt\-environment where a single
+minion can have multiple masters and fail\-over between them if its current
+master fails.
+.sp
+The individual steps are
+.INDENT 0.0
+.IP \(bu 2
+setup the master(s) to sign its auth\-replies
+.IP \(bu 2
+setup minion(s) to verify master\-public\-keys
+.IP \(bu 2
+enable multiple masters on minion(s)
+.IP \(bu 2
+enable master\-check on minion(s)
+.INDENT 2.0
+.INDENT 3.5
+Please note, that it is advised to have good knowledge of the salt\-
+authentication and communication\-process to understand this tutorial.
+All of the settings described here, go on top of the default
+authentication/communication process.
+.UNINDENT
+.UNINDENT
+.UNINDENT
+.SS Motivation
+.sp
+The default behaviour of a salt\-minion is to connect to a master and accept
+the masters public key. With each publication, the master sends his public\-key
+for the minion to check and if this public\-key ever changes, the minion
+complains and exits. Practically this means, that there can only be a single
+master at any given time.
+.sp
+Would it not be much nicer, if the minion could have any number of masters
+(1:n) and jump to the next master if its current master died because of a
+network or hardware failure?
+.sp
+\fBNOTE:\fP
+.INDENT 0.0
+.INDENT 3.5
+There is also a MultiMaster\-Tutorial with a different approach and topology
+than this one, that might also suite your needs or might even be better suited
+\fI\%Multi\-Master Tutorial\fP
+.UNINDENT
+.UNINDENT
+.sp
+It is also desirable, to add some sort of authenticity\-check to the very first
+public key a minion receives from a master. Currently a minions takes the
+first masters public key for granted.
+.SS The Goal
+.sp
+Setup the master to sign the public key it sends to the minions and enable the
+minions to verify this signature for authenticity.
+.SS Prepping the master to sign its public key
+.sp
+For signing to work, both master and minion must have the signing and/or
+verification settings enabled. If the master signs the public key but the
+minion does not verify it, the minion will complain and exit. The same
+happens, when the master does not sign but the minion tries to verify.
+.sp
+The easiest way to have the master sign its public key is to set
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
-rename_moe:
- module.run:
- \- m_name: moe
- \- new_name: larry
- \- onlyif: id moe
+master_sign_pubkey: True
.ft P
.fi
.UNINDENT
.UNINDENT
+.sp
+After restarting the salt\-master service, the master will automatically
+generate a new key\-pair
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+master_sign.pem
+master_sign.pub
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+A custom name can be set for the signing key\-pair by setting
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+master_sign_key_name:
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+The master will then generate that key\-pair upon restart and use it for
+creating the public keys signature attached to the auth\-reply.
+.sp
+The computation is done for every auth\-request of a minion. If many minions
+auth very often, it is advised to use conf_master:\fImaster_pubkey_signature\fP
+and conf_master:\fImaster_use_pubkey_signature\fP settings described below.
+.sp
+If multiple masters are in use and should sign their auth\-replies, the signing
+key\-pair master_sign.* has to be copied to each master. Otherwise a minion
+will fail to verify the masters public when connecting to a different master
+than it did initially. That is because the public keys signature was created
+with a different signing key\-pair.
+.SS Prepping the minion to verify received public keys
+.sp
+The minion must have the public key (and only that one!) available to be
+able to verify a signature it receives. That public key (defaults to
+master_sign.pub) must be copied from the master to the minions pki\-directory.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+/etc/salt/pki/minion/master_sign.pub
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+\fBIMPORTANT:\fP
+.INDENT 0.0
+.INDENT 3.5
+DO NOT COPY THE master_sign.pem FILE. IT MUST STAY ON THE MASTER AND
+ONLY THERE!
+.UNINDENT
+.UNINDENT
+.sp
+When that is done, enable the signature checking in the minions configuration
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+verify_master_pubkey_sign: True
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+and restart the minion. For the first try, the minion should be run in manual
+debug mode.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+salt\-minion \-l debug
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Upon connecting to the master, the following lines should appear on the output:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+[DEBUG ] Attempting to authenticate with the Salt Master at 172.16.0.10
+[DEBUG ] Loaded minion key: /etc/salt/pki/minion/minion.pem
+[DEBUG ] salt.crypt.verify_signature: Loading public key
+[DEBUG ] salt.crypt.verify_signature: Verifying signature
+[DEBUG ] Successfully verified signature of master public key with verification public key master_sign.pub
+[INFO ] Received signed and verified master pubkey from master 172.16.0.10
+[DEBUG ] Decrypting the current master AES key
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+If the signature verification fails, something went wrong and it will look
+like this
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+[DEBUG ] Attempting to authenticate with the Salt Master at 172.16.0.10
+[DEBUG ] Loaded minion key: /etc/salt/pki/minion/minion.pem
+[DEBUG ] salt.crypt.verify_signature: Loading public key
+[DEBUG ] salt.crypt.verify_signature: Verifying signature
+[DEBUG ] Failed to verify signature of public key
+[CRITICAL] The Salt Master server\(aqs public key did not authenticate!
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+In a case like this, it should be checked, that the verification pubkey
+(master_sign.pub) on the minion is the same as the one on the master.
+.sp
+Once the verification is successful, the minion can be started in daemon mode
+again.
+.sp
+For the paranoid among us, its also possible to verify the publication whenever
+it is received from the master. That is, for every single auth\-attempt which
+can be quite frequent. For example just the start of the minion will force the
+signature to be checked 6 times for various things like auth, mine,
+highstate, etc.
+.sp
+If that is desired, enable the setting
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+always_verify_signature: True
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.SS Multiple Masters For A Minion
+.sp
+Configuring multiple masters on a minion is done by specifying two settings:
+.INDENT 0.0
+.IP \(bu 2
+a list of masters addresses
+.IP \(bu 2
+what type of master is defined
+.UNINDENT
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+master:
+ \- 172.16.0.10
+ \- 172.16.0.11
+ \- 172.16.0.12
+.ft P
+.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
-.TP
-\fBRenderers\fP
-Renderers use state configuration files written in a variety of languages,
-templating engines, or files. Salt\(aqs configuration management system is,
-under the hood, language agnostic.
-.INDENT 7.0
-.TP
-.B Full list of renderers
-Contains: a list of renderers.
-YAML is one choice, but many systems are available, from
-alternative templating engines to the PyDSL language for rendering
-sls formulas.
-.TP
-.B Renderers
-Contains: more information about renderers. Salt states are only
-concerned with the ultimate highstate data structure, not how the
-data structure was created.
+.INDENT 3.5
+.sp
+.nf
+.ft C
+master_type: failover
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+This tells the minion that all the master above are available for it to
+connect to. When started with this configuration, it will try the master
+in the order they are defined. To randomize that order, set
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+master_shuffle: True
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+The master\-list will then be shuffled before the first connection attempt.
+.sp
+The first master that accepts the minion, is used by the minion. If the
+master does not yet know the minion, that counts as accepted and the minion
+stays on that master.
+.sp
+For the minion to be able to detect if its still connected to its current
+master enable the check for it
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+master_alive_interval:
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+If the loss of the connection is detected, the minion will temporarily
+remove the failed master from the list and try one of the other masters
+defined (again shuffled if that is enabled).
+.SS Testing the setup
+.sp
+At least two running masters are needed to test the failover setup.
+.sp
+Both masters should be running and the minion should be running on the command
+line in debug mode
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+salt\-minion \-l debug
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+The minion will connect to the first master from its master list
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+[DEBUG ] Attempting to authenticate with the Salt Master at 172.16.0.10
+[DEBUG ] Loaded minion key: /etc/salt/pki/minion/minion.pem
+[DEBUG ] salt.crypt.verify_signature: Loading public key
+[DEBUG ] salt.crypt.verify_signature: Verifying signature
+[DEBUG ] Successfully verified signature of master public key with verification public key master_sign.pub
+[INFO ] Received signed and verified master pubkey from master 172.16.0.10
+[DEBUG ] Decrypting the current master AES key
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+A test.ping on the master the minion is currently connected to should be run to
+test connectivity.
+.sp
+If successful, that master should be turned off. A firewall\-rule denying the
+minions packets will also do the trick.
+.sp
+Depending on the configured conf_minion:\fImaster_alive_interval\fP, the minion
+will notice the loss of the connection and log it to its logfile.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+[INFO ] Connection to master 172.16.0.10 lost
+[INFO ] Trying to tune in to next master from master\-list
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+The minion will then remove the current master from the list and try connecting
+to the next master
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+[INFO ] Removing possibly failed master 172.16.0.10 from list of masters
+[WARNING ] Master ip address changed from 172.16.0.10 to 172.16.0.11
+[DEBUG ] Attempting to authenticate with the Salt Master at 172.16.0.11
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+If everything is configured correctly, the new masters public key will be
+verified successfully
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+[DEBUG ] Loaded minion key: /etc/salt/pki/minion/minion.pem
+[DEBUG ] salt.crypt.verify_signature: Loading public key
+[DEBUG ] salt.crypt.verify_signature: Verifying signature
+[DEBUG ] Successfully verified signature of master public key with verification public key master_sign.pub
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+the authentication with the new master is successful
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+[INFO ] Received signed and verified master pubkey from master 172.16.0.11
+[DEBUG ] Decrypting the current master AES key
+[DEBUG ] Loaded minion key: /etc/salt/pki/minion/minion.pem
+[INFO ] Authentication with master successful!
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+and the minion can be pinged again from its new master.
+.SS Performance Tuning
+.sp
+With the setup described above, the master computes a signature for every
+auth\-request of a minion. With many minions and many auth\-requests, that
+can chew up quite a bit of CPU\-Power.
+.sp
+To avoid that, the master can use a pre\-created signature of its public\-key.
+The signature is saved as a base64 encoded string which the master reads
+once when starting and attaches only that string to auth\-replies.
+.sp
+Enabling this also gives paranoid users the possibility, to have the signing
+key\-pair on a different system than the actual salt\-master and create the public
+keys signature there. Probably on a system with more restrictive firewall rules,
+without internet access, less users, etc.
+.sp
+That signature can be created with
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+salt\-key \-\-gen\-signature
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+This will create a default signature file in the master pki\-directory
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+/etc/salt/pki/master/master_pubkey_signature
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+It is a simple text\-file with the binary\-signature converted to base64.
+.sp
+If no signing\-pair is present yet, this will auto\-create the signing pair and
+the signature file in one call
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+salt\-key \-\-gen\-signature \-\-auto\-create
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Telling the master to use the pre\-created signature is done with
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+master_use_pubkey_signature: True
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+That requires the file \(aqmaster_pubkey_signature\(aq to be present in the masters
+pki\-directory with the correct signature.
+.sp
+If the signature file is named differently, its name can be set with
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+master_pubkey_signature:
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+With many masters and many public\-keys (default and signing), it is advised to
+use the salt\-masters hostname for the signature\-files name. Signatures can be
+easily confused because they do not provide any information about the key the
+signature was created from.
+.sp
+Verifying that everything works is done the same way as above.
+.SS How the signing and verification works
+.sp
+The default key\-pair of the salt\-master is
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+/etc/salt/pki/master/master.pem
+/etc/salt/pki/master/master.pub
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+To be able to create a signature of a message (in this case a public\-key),
+another key\-pair has to be added to the setup. Its default name is:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+master_sign.pem
+master_sign.pub
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+The combination of the master.* and master_sign.* key\-pairs give the
+possibility of generating signatures. The signature of a given message
+is unique and can be verified, if the public\-key of the signing\-key\-pair
+is available to the recipient (the minion).
+.sp
+The signature of the masters public\-key in master.pub is computed with
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+master_sign.pem
+master.pub
+M2Crypto.EVP.sign_update()
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+This results in a binary signature which is converted to base64 and attached
+to the auth\-reply send to the minion.
+.sp
+With the signing\-pairs public\-key available to the minion, the attached
+signature can be verified with
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+master_sign.pub
+master.pub
+M2Cryptos EVP.verify_update().
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+When running multiple masters, either the signing key\-pair has to be present
+on all of them, or the master_pubkey_signature has to be pre\-computed for
+each master individually (because they all have different public\-keys).
+.INDENT 0.0
+.INDENT 3.5
+DO NOT PUT THE SAME master.pub ON ALL MASTERS FOR EASE OF USE.
+.UNINDENT
+.UNINDENT
+.SS Packaging External Modules for Salt
+.SS External Modules Setuptools Entry\-Points Support
+.sp
+The salt loader was enhanced to look for external modules by looking at the
+\fIsalt.loader\fP entry\-point:
+.INDENT 0.0
+.INDENT 3.5
+\fI\%https://pythonhosted.org/setuptools/setuptools.html#dynamic\-discovery\-of\-services\-and\-plugins\fP
+.UNINDENT
+.UNINDENT
+.sp
+\fIpkg_resources\fP should be installed, which is normally included in setuptools.
+.INDENT 0.0
+.INDENT 3.5
+\fI\%https://pythonhosted.org/setuptools/pkg_resources.html\fP
+.UNINDENT
+.UNINDENT
+.sp
+The package which has custom engines, minion modules, outputters, etc, should
+require setuptools and should define the following entry points in its setup
+function:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+from setuptools import setup, find_packages
+
+setup(name=,
+ version=,
+ description=,
+ author=,
+ author_email=,
+ url=\(aq ... \(aq,
+ packages=find_packages(),
+ entry_points=\(aq\(aq\(aq
+ [salt.loader]
+ engines_dirs = .:engines_dirs
+ fileserver_dirs = .:fileserver_dirs
+ pillar_dirs = .:pillar_dirs
+ returner_dirs = .:returner_dirs
+ roster_dirs = .:roster_dirs
+ \(aq\(aq\(aq)
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+The above setup script example mentions a loader module. here\(aqs an example of
+how \fI/.py\fP it should look:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+# \-*\- coding: utf\-8 \-*\-
+
+# Import python libs
+import os
+
+PKG_DIR = os.path.abspath(os.path.dirname(__file__))
+
+
+def engines_dirs():
+ \(aq\(aq\(aq
+ yield one path per parent directory of where engines can be found
+ \(aq\(aq\(aq
+ yield os.path.join(PKG_DIR, \(aqengines_1\(aq)
+ yield os.path.join(PKG_DIR, \(aqengines_2\(aq)
+
+
+def fileserver_dirs():
+ \(aq\(aq\(aq
+ yield one path per parent directory of where fileserver modules can be found
+ \(aq\(aq\(aq
+ yield os.path.join(PKG_DIR, \(aqfileserver\(aq)
+
+
+def pillar_dirs():
+ \(aq\(aq\(aq
+ yield one path per parent directory of where external pillar modules can be found
+ \(aq\(aq\(aq
+ yield os.path.join(PKG_DIR, \(aqpillar\(aq)
+
+
+def returner_dirs():
+ \(aq\(aq\(aq
+ yield one path per parent directory of where returner modules can be found
+ \(aq\(aq\(aq
+ yield os.path.join(PKG_DIR, \(aqreturners\(aq)
+
+
+def roster_dirs():
+ \(aq\(aq\(aq
+ yield one path per parent directory of where roster modules can be found
+ \(aq\(aq\(aq
+ yield os.path.join(PKG_DIR, \(aqroster\(aq)
+.ft P
+.fi
.UNINDENT
.UNINDENT
.SS How Do I Use Salt States?
@@ -40527,10 +42256,11 @@ file is just a data structure under the hood. While understanding that the SLS
is just a data structure isn\(aqt critical for understanding and making use of
Salt States, it should help bolster knowledge of where the real power is.
.sp
-SLS files are therefore, in reality, just \fI\%dictionaries\fP, \fI\%lists\fP, \fI\%strings\fP, and \fI\%numbers\fP\&.
-By using this approach Salt can be much more flexible. As one writes more state
-files, it becomes clearer exactly what is being written. The result is a system
-that is easy to understand, yet grows with the needs of the admin or developer.
+SLS files are therefore, in reality, just dictionaries, lists, strings, and
+numbers. By using this approach Salt can be much more flexible. As one writes
+more state files, it becomes clearer exactly what is being written. The result
+is a system that is easy to understand, yet grows with the needs of the admin
+or developer.
.SS The Top File
.sp
The example SLS files in the below sections can be assigned to hosts using a
@@ -42256,6 +43986,5670 @@ and we\(aqd love to hear from you.
.sp
In addition, by continuing to the Orchestrate Runner docs,
you can learn about the powerful orchestration of which Salt is capable.
+.SS States Tutorial, Part 5 \- Orchestration with Salt
+.sp
+This was moved to Orchestrate Runner\&.
+.SS Using Salt with Stormpath
+.sp
+\fI\%Stormpath\fP is a user management and authentication
+service. This tutorial covers using SaltStack to manage and take advantage of
+Stormpath\(aqs features.
+.SS External Authentication
+.sp
+Stormpath can be used for Salt\(aqs external authentication system. In order to do
+this, the master should be configured with an \fBapiid\fP, \fBapikey\fP, and the ID
+of the \fBapplication\fP that is associated with the users to be authenticated:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+stormpath:
+ apiid: 367DFSF4FRJ8767FSF4G34FGH
+ apikey: FEFREF43t3FEFRe/f323fwer4FWF3445gferWRWEer1
+ application: 786786FREFrefreg435fr1
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+\fBNOTE:\fP
+.INDENT 0.0
+.INDENT 3.5
+These values can be found in the \fIStormpath dashboard
+\(ga_\fP\&.
+.UNINDENT
+.UNINDENT
+.sp
+Users that are to be authenticated should be set up under the \fBstormpath\fP
+dict under \fBexternal_auth\fP:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+external_auth:
+ stormpath:
+ larry:
+ \- .*
+ \- \(aq@runner\(aq
+ \- \(aq@wheel\(aq
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Keep in mind that while Stormpath defaults the username associated with the
+account to the email address, it is better to use a username without an \fB@\fP
+sign in it.
+.SS Configuring Stormpath Modules
+.sp
+Stormpath accounts can be managed via either an execution or state module. In
+order to use either, a minion must be configured with an API ID and key.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+stormpath:
+ apiid: 367DFSF4FRJ8767FSF4G34FGH
+ apikey: FEFREF43t3FEFRe/f323fwer4FWF3445gferWRWEer1
+ directory: efreg435fr1786786FREFr
+ application: 786786FREFrefreg435fr1
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Some functions in the \fBstormpath\fP modules can make use of other options. The
+following options are also available.
+.SS directory
+.sp
+The ID of the directory that is to be used with this minion. Many functions
+require an ID to be specified to do their work. However, if the ID of a
+\fBdirectory\fP is specified, then Salt can often look up the resource in
+question.
+.SS application
+.sp
+The ID of the application that is to be used with this minion. Many functions
+require an ID to be specified to do their work. However, if the ID of a
+\fBapplication\fP is specified, then Salt can often look up the resource in
+question.
+.SS Managing Stormpath Accounts
+.sp
+With the \fBstormpath\fP configuration in place, Salt can be used to configure
+accounts (which may be thought of as users) on the Stormpath service. The
+following functions are available.
+.SS stormpath.create_account
+.sp
+Create an account on the Stormpath service. This requires a \fBdirectory_id\fP as
+the first argument; it will not be retrieved from the minion configuration. An
+\fBemail\fP address, \fBpassword\fP, first name (\fBgivenName\fP) and last name
+(\fBsurname\fP) are also required. For the full list of other parameters that may
+be specified, see:
+.sp
+\fI\%http://docs.stormpath.com/rest/product\-guide/#account\-resource\fP
+.sp
+When executed with no errors, this function will return the information about
+the account, from Stormpath.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+salt myminion stormpath.create_account shemp@example.com letmein Shemp Howard
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.SS stormpath.list_accounts
+.sp
+Show all accounts on the Stormpath service. This will return all accounts,
+regardless of directory, application, or group.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+salt myminion stormpath.list_accounts
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.SS stormpath.show_account
+.sp
+Show the details for a specific Stormpath account. An \fBaccount_id\fP is normally
+required. However, if am \fBemail\fP is provided instead, along with either a
+\fBdirectory_id\fP, \fBapplication_id\fP, or \fBgroup_id\fP, then Salt will search the
+specified resource to try and locate the \fBaccount_id\fP\&.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+salt myminion stormpath.show_account
+salt myminion stormpath.show_account email= directory_id=
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.SS stormpath.update_account
+.sp
+Update one or more items for this account. Specifying an empty value will clear
+it for that account. This function may be used in one of two ways. In order to
+update only one key/value pair, specify them in order:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+salt myminion stormpath.update_account givenName shemp
+salt myminion stormpath.update_account middleName \(aq\(aq
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+In order to specify multiple items, they need to be passed in as a dict. From
+the command line, it is best to do this as a JSON string:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+salt myminion stormpath.update_account items=\(aq{"givenName": "Shemp"}
+salt myminion stormpath.update_account items=\(aq{"middlename": ""}
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+When executed with no errors, this function will return the information about
+the account, from Stormpath.
+.SS stormpath.delete_account
+.sp
+Delete an account from Stormpath.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+salt myminion stormpath.delete_account
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.SS stormpath.list_directories
+.sp
+Show all directories associated with this tenant.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+salt myminion stormpath.list_directories
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.SS Using Stormpath States
+.sp
+Stormpath resources may be managed using the state system. The following states
+are available.
+.SS stormpath_account.present
+.sp
+Ensure that an account exists on the Stormpath service. All options that are
+available with the \fBstormpath.create_account\fP function are available here.
+If an account needs to be created, then this function will require the same
+fields that \fBstormpath.create_account\fP requires, including the \fBpassword\fP\&.
+However, if a password changes for an existing account, it will NOT be updated
+by this state.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+curly@example.com:
+ stormpath_account.present:
+ \- directory_id: efreg435fr1786786FREFr
+ \- password: badpass
+ \- firstName: Curly
+ \- surname: Howard
+ \- nickname: curly
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+It is advisable to always set a \fBnickname\fP that is not also an email address,
+so that it can be used by Salt\(aqs external authentication module.
+.SS stormpath_account.absent
+.sp
+Ensure that an account does not exist on Stormpath. As with
+\fBstormpath_account.present\fP, the \fBname\fP supplied to this state is the
+\fBemail\fP address associated with this account. Salt will use this, with or
+without the \fBdirectory\fP ID that is configured for the minion. However, lookups
+will be much faster with a directory ID specified.
+.SS Syslog\-ng usage
+.SS Overview
+.sp
+Syslog_ng state module is for generating syslog\-ng
+configurations. You can do the following things:
+.INDENT 0.0
+.IP \(bu 2
+generate syslog\-ng configuration from YAML,
+.IP \(bu 2
+use non\-YAML configuration,
+.IP \(bu 2
+start, stop or reload syslog\-ng.
+.UNINDENT
+.sp
+There is also an execution module, which can check the syntax of the
+configuration, get the version and other information about syslog\-ng.
+.SS Configuration
+.sp
+Users can create syslog\-ng configuration statements with the
+\fBsyslog_ng.config\fP function. It requires
+a \fIname\fP and a \fIconfig\fP parameter. The \fIname\fP parameter determines the name of
+the generated statement and the \fIconfig\fP parameter holds a parsed YAML structure.
+.sp
+A statement can be declared in the following forms (both are equivalent):
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+source.s_localhost:
+ syslog_ng.config:
+ \- config:
+ \- tcp:
+ \- ip: "127.0.0.1"
+ \- port: 1233
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+s_localhost:
+ syslog_ng.config:
+ \- config:
+ source:
+ \- tcp:
+ \- ip: "127.0.0.1"
+ \- port: 1233
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+The first one is called short form, because it needs less typing. Users can use lists
+and dictionaries to specify their configuration. The format is quite self describing and
+there are more examples [at the end](#examples) of this document.
+.SS Quotation
+.INDENT 0.0
+.TP
+.B The quotation can be tricky sometimes but here are some rules to follow:
+.INDENT 7.0
+.IP \(bu 2
+when a string meant to be \fB"string"\fP in the generated configuration, it should be like \fB\(aq"string"\(aq\fP in the YAML document
+.IP \(bu 2
+similarly, users should write \fB"\(aqstring\(aq"\fP to get \fB\(aqstring\(aq\fP in the generated configuration
+.UNINDENT
+.UNINDENT
+.SS Full example
+.sp
+The following configuration is an example, how a complete syslog\-ng configuration looks like:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+# Set the location of the configuration file
+set_location:
+ module.run:
+ \- name: syslog_ng.set_config_file
+ \- m_name: "/home/tibi/install/syslog\-ng/etc/syslog\-ng.conf"
+
+# The syslog\-ng and syslog\-ng\-ctl binaries are here. You needn\(aqt use
+# this method if these binaries can be found in a directory in your PATH.
+set_bin_path:
+ module.run:
+ \- name: syslog_ng.set_binary_path
+ \- m_name: "/home/tibi/install/syslog\-ng/sbin"
+
+# Writes the first lines into the config file, also erases its previous
+# content
+write_version:
+ module.run:
+ \- name: syslog_ng.write_version
+ \- m_name: "3.6"
+
+# There is a shorter form to set the above variables
+set_variables:
+ module.run:
+ \- name: syslog_ng.set_parameters
+ \- version: "3.6"
+ \- binary_path: "/home/tibi/install/syslog\-ng/sbin"
+ \- config_file: "/home/tibi/install/syslog\-ng/etc/syslog\-ng.conf"
+
+
+# Some global options
+options.global_options:
+ syslog_ng.config:
+ \- config:
+ \- time_reap: 30
+ \- mark_freq: 10
+ \- keep_hostname: "yes"
+
+source.s_localhost:
+ syslog_ng.config:
+ \- config:
+ \- tcp:
+ \- ip: "127.0.0.1"
+ \- port: 1233
+
+destination.d_log_server:
+ syslog_ng.config:
+ \- config:
+ \- tcp:
+ \- "127.0.0.1"
+ \- port: 1234
+
+log.l_log_to_central_server:
+ syslog_ng.config:
+ \- config:
+ \- source: s_localhost
+ \- destination: d_log_server
+
+some_comment:
+ module.run:
+ \- name: syslog_ng.write_config
+ \- config: |
+ # Multi line
+ # comment
+
+# Another mode to use comments or existing configuration snippets
+config.other_comment_form:
+ syslog_ng.config:
+ \- config: |
+ # Multi line
+ # comment
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+The \fBsyslog_ng.reloaded\fP function can generate syslog\-ng configuration from YAML. If the statement (source, destination, parser,
+etc.) has a name, this function uses the id as the name, otherwise (log
+statement) it\(aqs purpose is like a mandatory comment.
+.sp
+After execution this example the syslog_ng state will generate this
+file:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+#Generated by Salt on 2014\-08\-18 00:11:11
+@version: 3.6
+
+options {
+ time_reap(
+ 30
+ );
+ mark_freq(
+ 10
+ );
+ keep_hostname(
+ yes
+ );
+};
+
+
+source s_localhost {
+ tcp(
+ ip(
+ 127.0.0.1
+ ),
+ port(
+ 1233
+ )
+ );
+};
+
+
+destination d_log_server {
+ tcp(
+ 127.0.0.1,
+ port(
+ 1234
+ )
+ );
+};
+
+
+log {
+ source(
+ s_localhost
+ );
+ destination(
+ d_log_server
+ );
+};
+
+
+# Multi line
+# comment
+
+
+# Multi line
+# comment
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Users can include arbitrary texts in the generated configuration with
+using the \fBconfig\fP statement (see the example above).
+.SS Syslog_ng module functions
+.sp
+You can use \fBsyslog_ng.set_binary_path\fP
+to set the directory which contains the
+syslog\-ng and syslog\-ng\-ctl binaries. If this directory is in your PATH,
+you don\(aqt need to use this function. There is also a \fBsyslog_ng.set_config_file\fP
+function to set the location of the configuration file.
+.SS Examples
+.SS Simple source
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+source s_tail {
+ file(
+ "/var/log/apache/access.log",
+ follow_freq(1),
+ flags(no\-parse, validate\-utf8)
+ );
+};
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+s_tail:
+ # Salt will call the source function of syslog_ng module
+ syslog_ng.config:
+ \- config:
+ source:
+ \- file:
+ \- file: \(aq\(aq"/var/log/apache/access.log"\(aq\(aq
+ \- follow_freq : 1
+ \- flags:
+ \- no\-parse
+ \- validate\-utf8
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+OR
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+s_tail:
+ syslog_ng.config:
+ \- config:
+ source:
+ \- file:
+ \- \(aq\(aq"/var/log/apache/access.log"\(aq\(aq
+ \- follow_freq : 1
+ \- flags:
+ \- no\-parse
+ \- validate\-utf8
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+OR
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+source.s_tail:
+ syslog_ng.config:
+ \- config:
+ \- file:
+ \- \(aq\(aq"/var/log/apache/access.log"\(aq\(aq
+ \- follow_freq : 1
+ \- flags:
+ \- no\-parse
+ \- validate\-utf8
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.SS Complex source
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+source s_gsoc2014 {
+ tcp(
+ ip("0.0.0.0"),
+ port(1234),
+ flags(no\-parse)
+ );
+};
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+s_gsoc2014:
+ syslog_ng.config:
+ \- config:
+ source:
+ \- tcp:
+ \- ip: 0.0.0.0
+ \- port: 1234
+ \- flags: no\-parse
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.SS Filter
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+filter f_json {
+ match(
+ "@json:"
+ );
+};
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+f_json:
+ syslog_ng.config:
+ \- config:
+ filter:
+ \- match:
+ \- \(aq\(aq"@json:"\(aq\(aq
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.SS Template
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+template t_demo_filetemplate {
+ template(
+ "$ISODATE $HOST $MSG "
+ );
+ template_escape(
+ no
+ );
+};
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+t_demo_filetemplate:
+ syslog_ng.config:
+ \-config:
+ template:
+ \- template:
+ \- \(aq"$ISODATE $HOST $MSG\en"\(aq
+ \- template_escape:
+ \- "no"
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.SS Rewrite
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+rewrite r_set_message_to_MESSAGE {
+ set(
+ "${.json.message}",
+ value("$MESSAGE")
+ );
+};
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+r_set_message_to_MESSAGE:
+ syslog_ng.config:
+ \- config:
+ rewrite:
+ \- set:
+ \- \(aq"${.json.message}"\(aq
+ \- value : \(aq"$MESSAGE"\(aq
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.SS Global options
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+options {
+ time_reap(30);
+ mark_freq(10);
+ keep_hostname(yes);
+};
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+global_options:
+ syslog_ng.config:
+ \- config:
+ options:
+ \- time_reap: 30
+ \- mark_freq: 10
+ \- keep_hostname: "yes"
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.SS Log
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+log {
+ source(s_gsoc2014);
+ junction {
+ channel {
+ filter(f_json);
+ parser(p_json);
+ rewrite(r_set_json_tag);
+ rewrite(r_set_message_to_MESSAGE);
+ destination {
+ file(
+ "/tmp/json\-input.log",
+ template(t_gsoc2014)
+ );
+ };
+ flags(final);
+ };
+ channel {
+ filter(f_not_json);
+ parser {
+ syslog\-parser(
+
+ );
+ };
+ rewrite(r_set_syslog_tag);
+ flags(final);
+ };
+ };
+ destination {
+ file(
+ "/tmp/all.log",
+ template(t_gsoc2014)
+ );
+ };
+};
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+l_gsoc2014:
+ syslog_ng.config:
+ \- config:
+ log:
+ \- source: s_gsoc2014
+ \- junction:
+ \- channel:
+ \- filter: f_json
+ \- parser: p_json
+ \- rewrite: r_set_json_tag
+ \- rewrite: r_set_message_to_MESSAGE
+ \- destination:
+ \- file:
+ \- \(aq"/tmp/json\-input.log"\(aq
+ \- template: t_gsoc2014
+ \- flags: final
+ \- channel:
+ \- filter: f_not_json
+ \- parser:
+ \- syslog\-parser: []
+ \- rewrite: r_set_syslog_tag
+ \- flags: final
+ \- destination:
+ \- file:
+ \- "/tmp/all.log"
+ \- template: t_gsoc2014
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.SS Salt in 10 Minutes
+.sp
+\fBNOTE:\fP
+.INDENT 0.0
+.INDENT 3.5
+Welcome to SaltStack! I am excited that you are interested in Salt and
+starting down the path to better infrastructure management. I developed
+(and am continuing to develop) Salt with the goal of making the best
+software available to manage computers of almost any kind. I hope you enjoy
+working with Salt and that the software can solve your real world needs!
+.INDENT 0.0
+.IP \(bu 2
+Thomas S Hatch
+.IP \(bu 2
+Salt creator and Chief Developer
+.IP \(bu 2
+CTO of SaltStack, Inc.
+.UNINDENT
+.UNINDENT
+.UNINDENT
+.SS Getting Started
+.SS What is Salt?
+.sp
+Salt is a different approach to infrastructure management, founded on
+the idea that high\-speed communication with large numbers of systems can open
+up new capabilities. This approach makes Salt a powerful multitasking system
+that can solve many specific problems in an infrastructure.
+.sp
+The backbone of Salt is the remote execution engine, which creates a high\-speed,
+secure and bi\-directional communication net for groups of systems. On top of this
+communication system, Salt provides an extremely fast, flexible, and easy\-to\-use
+configuration management system called \fBSalt States\fP\&.
+.SS Installing Salt
+.sp
+SaltStack has been made to be very easy to install and get started. The
+installation documents contain instructions
+for all supported platforms.
+.SS Starting Salt
+.sp
+Salt functions on a master/minion topology. A master server acts as a
+central control bus for the clients, which are called \fBminions\fP\&. The minions
+connect back to the master.
+.SS Setting Up the Salt Master
+.sp
+Turning on the Salt Master is easy \-\- just turn it on! The default configuration
+is suitable for the vast majority of installations. The Salt Master can be
+controlled by the local Linux/Unix service manager:
+.sp
+On Systemd based platforms (newer Debian, openSUSE, Fedora):
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+systemctl start salt\-master
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+On Upstart based systems (Ubuntu, older Fedora/RHEL):
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+service salt\-master start
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+On SysV Init systems (Gentoo, older Debian etc.):
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+/etc/init.d/salt\-master start
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Alternatively, the Master can be started directly on the command\-line:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+salt\-master \-d
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+The Salt Master can also be started in the foreground in debug mode, thus
+greatly increasing the command output:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+salt\-master \-l debug
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+The Salt Master needs to bind to two TCP network ports on the system. These ports
+are \fB4505\fP and \fB4506\fP\&. For more in depth information on firewalling these ports,
+the firewall tutorial is available here\&.
+.SS Finding the Salt Master
+.sp
+When a minion starts, by default it searches for a system that resolves to the \fBsalt\fP hostname on the network.
+If found, the minion initiates the handshake and key authentication process with the Salt master.
+This means that the easiest configuration approach is to set internal DNS to resolve the name \fBsalt\fP back to the Salt Master IP.
+.sp
+Otherwise, the minion configuration file will need to be edited so that the
+configuration option \fBmaster\fP points to the DNS name or the IP of the Salt Master:
+.sp
+\fBNOTE:\fP
+.INDENT 0.0
+.INDENT 3.5
+The default location of the configuration files is \fB/etc/salt\fP\&. Most
+platforms adhere to this convention, but platforms such as FreeBSD and
+Microsoft Windows place this file in different locations.
+.UNINDENT
+.UNINDENT
+.sp
+\fB/etc/salt/minion:\fP
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+master: saltmaster.example.com
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.SS Setting up a Salt Minion
+.sp
+\fBNOTE:\fP
+.INDENT 0.0
+.INDENT 3.5
+The Salt Minion can operate with or without a Salt Master. This walk\-through
+assumes that the minion will be connected to the master, for information on
+how to run a master\-less minion please see the master\-less quick\-start guide:
+.sp
+Masterless Minion Quickstart
+.UNINDENT
+.UNINDENT
+.sp
+Now that the master can be found, start the minion in the same way as the
+master; with the platform init system or via the command line directly:
+.sp
+As a daemon:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+salt\-minion \-d
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+In the foreground in debug mode:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+salt\-minion \-l debug
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+When the minion is started, it will generate an \fBid\fP value, unless it has
+been generated on a previous run and cached (in \fB/etc/salt/minion_id\fP by
+default). This is the name by which the minion will attempt
+to authenticate to the master. The following steps are attempted, in order to
+try to find a value that is not \fBlocalhost\fP:
+.INDENT 0.0
+.IP 1. 3
+The Python function \fBsocket.getfqdn()\fP is run
+.IP 2. 3
+\fB/etc/hostname\fP is checked (non\-Windows only)
+.IP 3. 3
+\fB/etc/hosts\fP (\fB%WINDIR%\esystem32\edrivers\eetc\ehosts\fP on Windows hosts) is
+checked for hostnames that map to anything within \fB127.0.0.0/8\fP\&.
+.UNINDENT
+.sp
+If none of the above are able to produce an id which is not \fBlocalhost\fP, then
+a sorted list of IP addresses on the minion (excluding any within
+\fB127.0.0.0/8\fP) is inspected. The first publicly\-routable IP address is
+used, if there is one. Otherwise, the first privately\-routable IP address is
+used.
+.sp
+If all else fails, then \fBlocalhost\fP is used as a fallback.
+.sp
+\fBNOTE:\fP
+.INDENT 0.0
+.INDENT 3.5
+Overriding the \fBid\fP
+.sp
+The minion id can be manually specified using the \fBid\fP
+parameter in the minion config file. If this configuration value is
+specified, it will override all other sources for the \fBid\fP\&.
+.UNINDENT
+.UNINDENT
+.sp
+Now that the minion is started, it will generate cryptographic keys and attempt
+to connect to the master. The next step is to venture back to the master server
+and accept the new minion\(aqs public key.
+.SS Using salt\-key
+.sp
+Salt authenticates minions using public\-key encryption and authentication. For
+a minion to start accepting commands from the master, the minion keys need to be
+accepted by the master.
+.sp
+The \fBsalt\-key\fP command is used to manage all of the keys on the
+master. To list the keys that are on the master:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+salt\-key \-L
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+The keys that have been rejected, accepted, and pending acceptance are listed.
+The easiest way to accept the minion key is to accept all pending keys:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+salt\-key \-A
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+\fBNOTE:\fP
+.INDENT 0.0
+.INDENT 3.5
+Keys should be verified! Print the master key fingerprint by running \fBsalt\-key \-F master\fP
+on the Salt master. Copy the \fBmaster.pub\fP fingerprint from the Local Keys section,
+and then set this value as the \fBmaster_finger\fP in the minion configuration
+file. Restart the Salt minion.
+.sp
+On the master, run \fBsalt\-key \-f minion\-id\fP to print the fingerprint of the
+minion\(aqs public key that was received by the master. On the minion, run
+\fBsalt\-call key.finger \-\-local\fP to print the fingerprint of the minion key.
+.sp
+On the master:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+# salt\-key \-f foo.domain.com
+Unaccepted Keys:
+foo.domain.com: 39:f9:e4:8a:aa:74:8d:52:1a:ec:92:03:82:09:c8:f9
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+On the minion:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+# salt\-call key.finger \-\-local
+local:
+ 39:f9:e4:8a:aa:74:8d:52:1a:ec:92:03:82:09:c8:f9
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+If they match, approve the key with \fBsalt\-key \-a foo.domain.com\fP\&.
+.UNINDENT
+.UNINDENT
+.SS Sending the First Commands
+.sp
+Now that the minion is connected to the master and authenticated, the master
+can start to command the minion.
+.sp
+Salt commands allow for a vast set of functions to be executed and for
+specific minions and groups of minions to be targeted for execution.
+.sp
+The \fBsalt\fP command is comprised of command options, target specification,
+the function to execute, and arguments to the function.
+.sp
+A simple command to
+start with looks like this:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+salt \(aq*\(aq test.ping
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+The \fB*\fP is the target, which specifies all minions.
+.sp
+\fBtest.ping\fP tells the minion to run the \fBtest.ping\fP function.
+.sp
+In the case of \fBtest.ping\fP, \fBtest\fP refers to a execution module\&. \fBping\fP refers to the \fBping\fP function contained in the aforementioned \fBtest\fP
+module.
+.sp
+\fBNOTE:\fP
+.INDENT 0.0
+.INDENT 3.5
+Execution modules are the workhorses of Salt. They do the work on the
+system to perform various tasks, such as manipulating files and restarting
+services.
+.UNINDENT
+.UNINDENT
+.sp
+The result of running this command will be the master instructing all of the
+minions to execute \fBtest.ping\fP in parallel
+and return the result.
+.sp
+This is not an actual ICMP ping, but rather a simple function which returns \fBTrue\fP\&.
+Using \fBtest.ping\fP is a good way of confirming that a minion is
+connected.
+.sp
+\fBNOTE:\fP
+.INDENT 0.0
+.INDENT 3.5
+Each minion registers itself with a unique minion ID. This ID defaults to
+the minion\(aqs hostname, but can be explicitly defined in the minion config as
+well by using the \fBid\fP parameter.
+.UNINDENT
+.UNINDENT
+.sp
+Of course, there are hundreds of other modules that can be called just as
+\fBtest.ping\fP can. For example, the following would return disk usage on all
+targeted minions:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+salt \(aq*\(aq disk.usage
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.SS Getting to Know the Functions
+.sp
+Salt comes with a vast library of functions available for execution, and Salt
+functions are self\-documenting. To see what functions are available on the
+minions execute the \fBsys.doc\fP function:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+salt \(aq*\(aq sys.doc
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+This will display a very large list of available functions and documentation on
+them.
+.sp
+\fBNOTE:\fP
+.INDENT 0.0
+.INDENT 3.5
+Module documentation is also available on the web\&.
+.UNINDENT
+.UNINDENT
+.sp
+These functions cover everything from shelling out to package management to
+manipulating database servers. They comprise a powerful system management API
+which is the backbone to Salt configuration management and many other aspects
+of Salt.
+.sp
+\fBNOTE:\fP
+.INDENT 0.0
+.INDENT 3.5
+Salt comes with many plugin systems. The functions that are available via
+the \fBsalt\fP command are called Execution Modules\&.
+.UNINDENT
+.UNINDENT
+.SS Helpful Functions to Know
+.sp
+The \fBcmd\fP module contains
+functions to shell out on minions, such as \fBcmd.run\fP and \fBcmd.run_all\fP:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+salt \(aq*\(aq cmd.run \(aqls \-l /etc\(aq
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+The \fBpkg\fP functions automatically map local system package managers to the
+same salt functions. This means that \fBpkg.install\fP will install packages via
+\fByum\fP on Red Hat based systems, \fBapt\fP on Debian systems, etc.:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+salt \(aq*\(aq pkg.install vim
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+\fBNOTE:\fP
+.INDENT 0.0
+.INDENT 3.5
+Some custom Linux spins and derivatives of other distributions are not properly
+detected by Salt. If the above command returns an error message saying that
+\fBpkg.install\fP is not available, then you may need to override the pkg
+provider. This process is explained here\&.
+.UNINDENT
+.UNINDENT
+.sp
+The \fBnetwork.interfaces\fP function will
+list all interfaces on a minion, along with their IP addresses, netmasks, MAC
+addresses, etc:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+salt \(aq*\(aq network.interfaces
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.SS Changing the Output Format
+.sp
+The default output format used for most Salt commands is called the \fBnested\fP
+outputter, but there are several other outputters that can be used to change
+the way the output is displayed. For instance, the \fBpprint\fP outputter can be
+used to display the return data using Python\(aqs \fBpprint\fP module:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+root@saltmaster:~# salt myminion grains.item pythonpath \-\-out=pprint
+{\(aqmyminion\(aq: {\(aqpythonpath\(aq: [\(aq/usr/lib64/python2.7\(aq,
+ \(aq/usr/lib/python2.7/plat\-linux2\(aq,
+ \(aq/usr/lib64/python2.7/lib\-tk\(aq,
+ \(aq/usr/lib/python2.7/lib\-tk\(aq,
+ \(aq/usr/lib/python2.7/site\-packages\(aq,
+ \(aq/usr/lib/python2.7/site\-packages/gst\-0.10\(aq,
+ \(aq/usr/lib/python2.7/site\-packages/gtk\-2.0\(aq]}}
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+The full list of Salt outputters, as well as example output, can be found
+here\&.
+.SS \fBsalt\-call\fP
+.sp
+The examples so far have described running commands from the Master using the
+\fBsalt\fP command, but when troubleshooting it can be more beneficial to login
+to the minion directly and use \fBsalt\-call\fP\&.
+.sp
+Doing so allows you to see the minion log messages specific to the command you
+are running (which are \fInot\fP part of the return data you see when running the
+command from the Master using \fBsalt\fP), making it unnecessary to tail the
+minion log. More information on \fBsalt\-call\fP and how to use it can be found
+here\&.
+.SS Grains
+.sp
+Salt uses a system called Grains to build up
+static data about minions. This data includes information about the operating
+system that is running, CPU architecture and much more. The grains system is
+used throughout Salt to deliver platform data to many components and to users.
+.sp
+Grains can also be statically set, this makes it easy to assign values to
+minions for grouping and managing.
+.sp
+A common practice is to assign grains to minions to specify what the role or
+roles a minion might be. These static grains can be set in the minion
+configuration file or via the \fBgrains.setval\fP
+function.
+.SS Targeting
+.sp
+Salt allows for minions to be targeted based on a wide range of criteria. The
+default targeting system uses globular expressions to match minions, hence if
+there are minions named \fBlarry1\fP, \fBlarry2\fP, \fBcurly1\fP, and \fBcurly2\fP, a
+glob of \fBlarry*\fP will match \fBlarry1\fP and \fBlarry2\fP, and a glob of \fB*1\fP
+will match \fBlarry1\fP and \fBcurly1\fP\&.
+.sp
+Many other targeting systems can be used other than globs, these systems
+include:
+.INDENT 0.0
+.TP
+.B Regular Expressions
+Target using PCRE\-compliant regular expressions
+.TP
+.B Grains
+Target based on grains data:
+Targeting with Grains
+.TP
+.B Pillar
+Target based on pillar data:
+Targeting with Pillar
+.TP
+.B IP
+Target based on IP address/subnet/range
+.TP
+.B Compound
+Create logic to target based on multiple targets:
+Targeting with Compound
+.TP
+.B Nodegroup
+Target with nodegroups:
+Targeting with Nodegroup
+.UNINDENT
+.sp
+The concepts of targets are used on the command line with Salt, but also
+function in many other areas as well, including the state system and the
+systems used for ACLs and user permissions.
+.SS Passing in Arguments
+.sp
+Many of the functions available accept arguments which can be passed in on
+the command line:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+salt \(aq*\(aq pkg.install vim
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+This example passes the argument \fBvim\fP to the pkg.install function. Since
+many functions can accept more complex input than just a string, the arguments
+are parsed through YAML, allowing for more complex data to be sent on the
+command line:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+salt \(aq*\(aq test.echo \(aqfoo: bar\(aq
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+In this case Salt translates the string \(aqfoo: bar\(aq into the dictionary
+"{\(aqfoo\(aq: \(aqbar\(aq}"
+.sp
+\fBNOTE:\fP
+.INDENT 0.0
+.INDENT 3.5
+Any line that contains a newline will not be parsed by YAML.
+.UNINDENT
+.UNINDENT
+.SS Salt States
+.sp
+Now that the basics are covered the time has come to evaluate \fBStates\fP\&. Salt
+\fBStates\fP, or the \fBState System\fP is the component of Salt made for
+configuration management.
+.sp
+The state system is already available with a basic Salt setup, no additional
+configuration is required. States can be set up immediately.
+.sp
+\fBNOTE:\fP
+.INDENT 0.0
+.INDENT 3.5
+Before diving into the state system, a brief overview of how states are
+constructed will make many of the concepts clearer. Salt states are based
+on data modeling and build on a low level data structure that is used to
+execute each state function. Then more logical layers are built on top of
+each other.
+.sp
+The high layers of the state system which this tutorial will
+cover consists of everything that needs to be known to use states, the two
+high layers covered here are the \fIsls\fP layer and the highest layer
+\fIhighstate\fP\&.
+.sp
+Understanding the layers of data management in the State System will help with
+understanding states, but they never need to be used. Just as understanding
+how a compiler functions assists when learning a programming language,
+understanding what is going on under the hood of a configuration management
+system will also prove to be a valuable asset.
+.UNINDENT
+.UNINDENT
+.SS The First SLS Formula
+.sp
+The state system is built on SLS formulas. These formulas are built out in
+files on Salt\(aqs file server. To make a very basic SLS formula open up a file
+under /srv/salt named vim.sls. The following state ensures that vim is installed
+on a system to which that state has been applied.
+.sp
+\fB/srv/salt/vim.sls:\fP
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+vim:
+ pkg.installed
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Now install vim on the minions by calling the SLS directly:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+salt \(aq*\(aq state.apply vim
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+This command will invoke the state system and run the \fBvim\fP SLS.
+.sp
+Now, to beef up the vim SLS formula, a \fBvimrc\fP can be added:
+.sp
+\fB/srv/salt/vim.sls:\fP
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+vim:
+ pkg.installed: []
+
+/etc/vimrc:
+ file.managed:
+ \- source: salt://vimrc
+ \- mode: 644
+ \- user: root
+ \- group: root
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Now the desired \fBvimrc\fP needs to be copied into the Salt file server to
+\fB/srv/salt/vimrc\fP\&. In Salt, everything is a file, so no path redirection needs
+to be accounted for. The \fBvimrc\fP file is placed right next to the \fBvim.sls\fP file.
+The same command as above can be executed to all the vim SLS formulas and now
+include managing the file.
+.sp
+\fBNOTE:\fP
+.INDENT 0.0
+.INDENT 3.5
+Salt does not need to be restarted/reloaded or have the master manipulated
+in any way when changing SLS formulas. They are instantly available.
+.UNINDENT
+.UNINDENT
+.SS Adding Some Depth
+.sp
+Obviously maintaining SLS formulas right in a single directory at the root of
+the file server will not scale out to reasonably sized deployments. This is
+why more depth is required. Start by making an nginx formula a better way,
+make an nginx subdirectory and add an init.sls file:
+.sp
+\fB/srv/salt/nginx/init.sls:\fP
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+nginx:
+ pkg.installed: []
+ service.running:
+ \- require:
+ \- pkg: nginx
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+A few concepts are introduced in this SLS formula.
+.sp
+First is the service statement which ensures that the \fBnginx\fP service is running.
+.sp
+Of course, the nginx service can\(aqt be started unless the package is installed \-\-
+hence the \fBrequire\fP statement which sets up a dependency between the two.
+.sp
+The \fBrequire\fP statement makes sure that the required component is executed before
+and that it results in success.
+.sp
+\fBNOTE:\fP
+.INDENT 0.0
+.INDENT 3.5
+The \fIrequire\fP option belongs to a family of options called \fIrequisites\fP\&.
+Requisites are a powerful component of Salt States, for more information
+on how requisites work and what is available see:
+Requisites
+.sp
+Also evaluation ordering is available in Salt as well:
+Ordering States
+.UNINDENT
+.UNINDENT
+.sp
+This new sls formula has a special name \-\- \fBinit.sls\fP\&. When an SLS formula is
+named \fBinit.sls\fP it inherits the name of the directory path that contains it.
+This formula can be referenced via the following command:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+salt \(aq*\(aq state.apply nginx
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+\fBNOTE:\fP
+.INDENT 0.0
+.INDENT 3.5
+\fBstate.apply\fP is just another remote
+execution function, just like \fBtest.ping\fP
+or \fBdisk.usage\fP\&. It simply takes the
+name of an SLS file as an argument.
+.UNINDENT
+.UNINDENT
+.sp
+Now that subdirectories can be used, the \fBvim.sls\fP formula can be cleaned up.
+To make things more flexible, move the \fBvim.sls\fP and vimrc into a new subdirectory
+called \fBedit\fP and change the \fBvim.sls\fP file to reflect the change:
+.sp
+\fB/srv/salt/edit/vim.sls:\fP
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+vim:
+ pkg.installed
+
+/etc/vimrc:
+ file.managed:
+ \- source: salt://edit/vimrc
+ \- mode: 644
+ \- user: root
+ \- group: root
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Only the source path to the vimrc file has changed. Now the formula is
+referenced as \fBedit.vim\fP because it resides in the edit subdirectory.
+Now the edit subdirectory can contain formulas for emacs, nano, joe or any other
+editor that may need to be deployed.
+.SS Next Reading
+.sp
+Two walk\-throughs are specifically recommended at this point. First, a deeper
+run through States, followed by an explanation of Pillar.
+.INDENT 0.0
+.IP 1. 3
+Starting States
+.IP 2. 3
+Pillar Walkthrough
+.UNINDENT
+.sp
+An understanding of Pillar is extremely helpful in using States.
+.SS Getting Deeper Into States
+.sp
+Two more in\-depth States tutorials exist, which delve much more deeply into States
+functionality.
+.INDENT 0.0
+.IP 1. 3
+How Do I Use Salt States?, covers much
+more to get off the ground with States.
+.IP 2. 3
+The States Tutorial also provides a
+fantastic introduction.
+.UNINDENT
+.sp
+These tutorials include much more in\-depth information including templating
+SLS formulas etc.
+.SS So Much More!
+.sp
+This concludes the initial Salt walk\-through, but there are many more things still
+to learn! These documents will cover important core aspects of Salt:
+.INDENT 0.0
+.IP \(bu 2
+Pillar
+.IP \(bu 2
+Job Management
+.UNINDENT
+.sp
+A few more tutorials are also available:
+.INDENT 0.0
+.IP \(bu 2
+Remote Execution Tutorial
+.IP \(bu 2
+Standalone Minion
+.UNINDENT
+.sp
+This still is only scratching the surface, many components such as the reactor
+and event systems, extending Salt, modular components and more are not covered
+here. For an overview of all Salt features and documentation, look at the
+Table of Contents\&.
+.SS Salt\(aqs Test Suite: An Introduction
+.sp
+\fBNOTE:\fP
+.INDENT 0.0
+.INDENT 3.5
+This tutorial makes a couple of assumptions. The first assumption is that
+you have a basic knowledge of Salt. To get up to speed, check out the
+Salt Walkthrough\&.
+.sp
+The second assumption is that your Salt development environment is already
+configured and that you have a basic understanding of contributing to the
+Salt codebase. If you\(aqre unfamiliar with either of these topics, please refer
+to the Installing Salt for Development
+and the Contributing pages, respectively.
+.UNINDENT
+.UNINDENT
+.sp
+Salt comes with a powerful integration and unit test suite. The test suite
+allows for the fully automated run of integration and/or unit tests from a
+single interface.
+.sp
+Salt\(aqs test suite is located under the \fBtests\fP directory in the root of Salt\(aqs
+code base and is divided into two main types of tests:
+\fI\%unit tests and integration tests\fP\&. The \fBunit\fP and
+\fBintegration\fP sub\-test\-suites are located in the \fBtests\fP directory, which is
+where the majority of Salt\(aqs test cases are housed.
+.SS Getting Set Up For Tests
+.sp
+There are a couple of requirements, in addition to Salt\(aqs requirements, that need
+to be installed in order to run Salt\(aqs test suite. You can install these additional
+requirements using the files located in the \fBsalt/requirements\fP directory,
+depending on your relevant version of Python:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+pip install \-r requirements/dev_python27.txt
+pip install \-r requirements/dev_python34.txt
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+To be able to run integration tests which utilizes ZeroMQ transport, you also
+need to install additional requirements for it. Make sure you have installed
+the C/C++ compiler and development libraries and header files needed for your
+Python version.
+.sp
+This is an example for RedHat\-based operating systems:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+yum install gcc gcc\-c++ python\-devel
+pip install \-r requirements/zeromq.txt
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+On Debian, Ubuntu or their derivatives run the following commands:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+apt\-get install build\-essential python\-dev
+pip install \-r requirements/zeromq.txt
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+This will install the latest \fBpycrypto\fP and \fBpyzmq\fP (with bundled
+\fBlibzmq\fP) Python modules required for running integration tests suite.
+.SS Test Directory Structure
+.sp
+As noted in the introduction to this tutorial, Salt\(aqs test suite is located in the
+\fBtests\fP directory in the root of Salt\(aqs code base. From there, the tests are divided
+into two groups \fBintegration\fP and \fBunit\fP\&. Within each of these directories, the
+directory structure roughly mirrors the directory structure of Salt\(aqs own codebase.
+For example, the files inside \fBtests/integration/modules\fP contains tests for the
+files located within \fBsalt/modules\fP\&.
+.sp
+\fBNOTE:\fP
+.INDENT 0.0
+.INDENT 3.5
+\fBtests/integration\fP and \fBtests/unit\fP are the only directories discussed in
+this tutorial. With the exception of the \fBtests/runtests.py\fP file, which is
+used below in the \fI\%Running the Test Suite\fP section, the other directories and
+files located in \fBtests\fP are outside the scope of this tutorial.
+.UNINDENT
+.UNINDENT
+.SS Integration vs. Unit
+.sp
+Given that Salt\(aqs test suite contains two powerful, though very different, testing
+approaches, when should you write integration tests and when should you write unit
+tests?
+.sp
+Integration tests use Salt masters, minions, and a syndic to test salt functionality
+directly and focus on testing the interaction of these components. Salt\(aqs integration
+test runner includes functionality to run Salt execution modules, runners, states,
+shell commands, salt\-ssh commands, salt\-api commands, and more. This provides a
+tremendous ability to use Salt to test itself and makes writing such tests a breeze.
+Integration tests are the preferred method of testing Salt functionality when
+possible.
+.sp
+Unit tests do not spin up any Salt daemons, but instead find their value in testing
+singular implementations of individual functions. Instead of testing against specific
+interactions, unit tests should be used to test a function\(aqs logic. Unit tests should
+be used to test a function\(aqs exit point(s) such as any \fBreturn\fP or \fBraises\fP
+statements.
+.sp
+Unit tests are also useful in cases where writing an integration test might not be
+possible. While the integration test suite is extremely powerful, unfortunately at
+this time, it does not cover all functional areas of Salt\(aqs ecosystem. For example,
+at the time of this writing, there is not a way to write integration tests for Proxy
+Minions. Since the test runner will need to be adjusted to account for Proxy Minion
+processes, unit tests can still provide some testing support in the interim by
+testing the logic contained inside Proxy Minion functions.
+.SS Running the Test Suite
+.sp
+Once all of the \fI\%requirements\fP are installed, the
+\fBruntests.py\fP file in the \fBsalt/tests\fP directory is used to instantiate
+Salt\(aqs test suite:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+python tests/runtests.py [OPTIONS]
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+The command above, if executed without any options, will run the entire suite of
+integration and unit tests. Some tests require certain flags to run, such as
+destructive tests. If these flags are not included, then the test suite will only
+perform the tests that don\(aqt require special attention.
+.sp
+At the end of the test run, you will see a summary output of the tests that passed,
+failed, or were skipped.
+.sp
+The test runner also includes a \fB\-\-help\fP option that lists all of the various
+command line options:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+python tests/runtests.py \-\-help
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+You can also call the test runner as an executable:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+\&./tests/runtests.py \-\-help
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.SS Running Integration Tests
+.sp
+Salt\(aqs set of integration tests use Salt to test itself. The integration portion
+of the test suite includes some built\-in Salt daemons that will spin up in preparation
+of the test run. This list of Salt daemon processes includes:
+.INDENT 0.0
+.IP \(bu 2
+2 Salt Masters
+.IP \(bu 2
+2 Salt Minions
+.IP \(bu 2
+1 Salt Syndic
+.UNINDENT
+.sp
+These various daemons are used to execute Salt commands and functionality within
+the test suite, allowing you to write tests to assert against expected or
+unexpected behaviors.
+.sp
+A simple example of a test utilizing a typical master/minion execution module command
+is the test for the \fBtest_ping\fP function in the
+\fBtests/integration/modules/test_test.py\fP
+file:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+def test_ping(self):
+ \(aq\(aq\(aq
+ test.ping
+ \(aq\(aq\(aq
+ self.assertTrue(self.run_function(\(aqtest.ping\(aq))
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+The test above is a very simple example where the \fBtest.ping\fP function is
+executed by Salt\(aqs test suite runner and is asserting that the minion returned
+with a \fBTrue\fP response.
+.SS Test Selection Options
+.sp
+If you look in the output of the \fB\-\-help\fP command of the test runner, you will
+see a section called \fBTests Selection Options\fP\&. The options under this section
+contain various subsections of the integration test suite such as \fB\-\-modules\fP,
+\fB\-\-ssh\fP, or \fB\-\-states\fP\&. By selecting any one of these options, the test daemons
+will spin up and the integration tests in the named subsection will run.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+\&./tests/runtests.py \-\-modules
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+\fBNOTE:\fP
+.INDENT 0.0
+.INDENT 3.5
+The testing subsections listed in the \fBTests Selection Options\fP of the
+\fB\-\-help\fP output \fIonly\fP apply to the integration tests. They do not run unit
+tests.
+.UNINDENT
+.UNINDENT
+.SS Running Unit Tests
+.sp
+While \fB\&./tests/runtests.py\fP executes the \fIentire\fP test suite (barring any tests
+requiring special flags), the \fB\-\-unit\fP flag can be used to run \fIonly\fP Salt\(aqs
+unit tests. Salt\(aqs unit tests include the tests located in the \fBtests/unit\fP
+directory.
+.sp
+The unit tests do not spin up any Salt testing daemons as the integration tests
+do and execute very quickly compared to the integration tests.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+\&./tests/runtests.py \-\-unit
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.SS Running Specific Tests
+.sp
+There are times when a specific test file, test class, or even a single,
+individual test need to be executed, such as when writing new tests. In these
+situations, the \fB\-\-name\fP option should be used.
+.sp
+For running a single test file, such as the pillar module test file in the
+integration test directory, you must provide the file path using \fB\&.\fP instead
+of \fB/\fP as separators and no file extension:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+\&./tests/runtests.py \-\-name=integration.modules.test_pillar
+\&./tests/runtests.py \-n integration.modules.test_pillar
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Some test files contain only one test class while other test files contain multiple
+test classes. To run a specific test class within the file, append the name of
+the test class to the end of the file path:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+\&./tests/runtests.py \-\-name=integration.modules.test_pillar.PillarModuleTest
+\&./tests/runtests.py \-n integration.modules.test_pillar.PillarModuleTest
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+To run a single test within a file, append both the name of the test class the
+individual test belongs to, as well as the name of the test itself:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+\&./tests/runtests.py \e
+ \-\-name=integration.modules.test_pillar.PillarModuleTest.test_data
+\&./tests/runtests.py \e
+ \-n integration.modules.test_pillar.PillarModuleTest.test_data
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+The \fB\-\-name\fP and \fB\-n\fP options can be used for unit tests as well as integration
+tests. The following command is an example of how to execute a single test found in
+the \fBtests/unit/modules/test_cp.py\fP file:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+\&./tests/runtests.py \e
+ \-n unit.modules.test_cp.CpTestCase.test_get_template_success
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.SS Writing Tests for Salt
+.sp
+Once you\(aqre comfortable running tests, you can now start writing them! Be sure
+to review the \fI\%Integration vs. Unit\fP section of this tutorial to determine what
+type of test makes the most sense for the code you\(aqre testing.
+.sp
+\fBNOTE:\fP
+.INDENT 0.0
+.INDENT 3.5
+There are many decorators, naming conventions, and code specifications
+required for Salt test files. We will not be covering all of the these specifics
+in this tutorial. Please refer to the testing documentation links listed below
+in the \fI\%Additional Testing Documentation\fP section to learn more about these
+requirements.
+.sp
+In the following sections, the test examples assume the "new" test is added to
+a test file that is already present and regularly running in the test suite and
+is written with the correct requirements.
+.UNINDENT
+.UNINDENT
+.SS Writing Integration Tests
+.sp
+Since integration tests validate against a running environment, as explained in the
+\fI\%Running Integration Tests\fP section of this tutorial, integration tests are very
+easy to write and are generally the preferred method of writing Salt tests.
+.sp
+The following integration test is an example taken from the \fBtest.py\fP file in the
+\fBtests/integration/modules\fP directory. This test uses the \fBrun_function\fP method
+to test the functionality of a traditional execution module command.
+.sp
+The \fBrun_function\fP method uses the integration test daemons to execute a
+\fBmodule.function\fP command as you would with Salt. The minion runs the function and
+returns. The test also uses \fI\%Python\(aqs Assert Functions\fP to test that the
+minion\(aqs return is expected.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+def test_ping(self):
+ \(aq\(aq\(aq
+ test.ping
+ \(aq\(aq\(aq
+ self.assertTrue(self.run_function(\(aqtest.ping\(aq))
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Args can be passed in to the \fBrun_function\fP method as well:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+def test_echo(self):
+ \(aq\(aq\(aq
+ test.echo
+ \(aq\(aq\(aq
+ self.assertEqual(self.run_function(\(aqtest.echo\(aq, [\(aqtext\(aq]), \(aqtext\(aq)
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+The next example is taken from the
+\fBtests/integration/modules/test_aliases.py\fP file and
+demonstrates how to pass kwargs to the \fBrun_function\fP call. Also note that this
+test uses another salt function to ensure the correct data is present (via the
+\fBaliases.set_target\fP call) before attempting to assert what the \fBaliases.get_target\fP
+call should return.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+def test_set_target(self):
+ \(aq\(aq\(aq
+ aliases.set_target and aliases.get_target
+ \(aq\(aq\(aq
+ set_ret = self.run_function(
+ \(aqaliases.set_target\(aq,
+ alias=\(aqfred\(aq,
+ target=\(aqbob\(aq)
+ self.assertTrue(set_ret)
+ tgt_ret = self.run_function(
+ \(aqaliases.get_target\(aq,
+ alias=\(aqfred\(aq)
+ self.assertEqual(tgt_ret, \(aqbob\(aq)
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Using multiple Salt commands in this manner provides two useful benefits. The first is
+that it provides some additional coverage for the \fBaliases.set_target\fP function.
+The second benefit is the call to \fBaliases.get_target\fP is not dependent on the
+presence of any aliases set outside of this test. Tests should not be dependent on
+the previous execution, success, or failure of other tests. They should be isolated
+from other tests as much as possible.
+.sp
+While it might be tempting to build out a test file where tests depend on one another
+before running, this should be avoided. SaltStack recommends that each test should
+test a single functionality and not rely on other tests. Therefore, when possible,
+individual tests should also be broken up into singular pieces. These are not
+hard\-and\-fast rules, but serve more as recommendations to keep the test suite simple.
+This helps with debugging code and related tests when failures occur and problems
+are exposed. There may be instances where large tests use many asserts to set up a
+use case that protects against potential regressions.
+.sp
+\fBNOTE:\fP
+.INDENT 0.0
+.INDENT 3.5
+The examples above all use the \fBrun_function\fP option to test execution module
+functions in a traditional master/minion environment. To see examples of how to
+test other common Salt components such as runners, salt\-api, and more, please
+refer to the Integration Test Class Examples
+documentation.
+.UNINDENT
+.UNINDENT
+.SS Destructive vs Non\-destructive Tests
+.sp
+Since Salt is used to change the settings and behavior of systems, often, the
+best approach to run tests is to make actual changes to an underlying system.
+This is where the concept of destructive integration tests comes into play.
+Tests can be written to alter the system they are running on. This capability
+is what fills in the gap needed to properly test aspects of system management
+like package installation.
+.sp
+To write a destructive test, import and use the \fBdestructiveTest\fP decorator for
+the test method:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+import integration
+from tests.support.helpers import destructiveTest
+
+class PkgTest(integration.ModuleCase):
+ @destructiveTest
+ def test_pkg_install(self):
+ ret = self.run_function(\(aqpkg.install\(aq, name=\(aqfinch\(aq)
+ self.assertSaltTrueReturn(ret)
+ ret = self.run_function(\(aqpkg.purge\(aq, name=\(aqfinch\(aq)
+ self.assertSaltTrueReturn(ret)
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.SS Writing Unit Tests
+.sp
+As explained in the \fI\%Integration vs. Unit\fP section above, unit tests should be
+written to test the \fIlogic\fP of a function. This includes focusing on testing
+\fBreturn\fP and \fBraises\fP statements. Substantial effort should be made to mock
+external resources that are used in the code being tested.
+.sp
+External resources that should be mocked include, but are not limited to, APIs,
+function calls, external data either globally available or passed in through
+function arguments, file data, etc. This practice helps to isolate unit tests to
+test Salt logic. One handy way to think about writing unit tests is to "block
+all of the exits". More information about how to properly mock external resources
+can be found in Salt\(aqs Unit Test documentation.
+.sp
+Salt\(aqs unit tests utilize Python\(aqs mock class as well as \fI\%MagicMock\fP\&. The
+\fB@patch\fP decorator is also heavily used when "blocking all the exits".
+.sp
+A simple example of a unit test currently in use in Salt is the
+\fBtest_get_file_not_found\fP test in the \fBtests/unit/modules/test_cp.py\fP file.
+This test uses the \fB@patch\fP decorator and \fBMagicMock\fP to mock the return
+of the call to Salt\(aqs \fBcp.hash_file\fP execution module function. This ensures
+that we\(aqre testing the \fBcp.get_file\fP function directly, instead of inadvertently
+testing the call to \fBcp.hash_file\fP, which is used in \fBcp.get_file\fP\&.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+def test_get_file_not_found(self):
+ \(aq\(aq\(aq
+ Test if get_file can\(aqt find the file.
+ \(aq\(aq\(aq
+ with patch(\(aqsalt.modules.cp.hash_file\(aq, MagicMock(return_value=False)):
+ path = \(aqsalt://saltines\(aq
+ dest = \(aq/srv/salt/cheese\(aq
+ ret = \(aq\(aq
+ self.assertEqual(cp.get_file(path, dest), ret)
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Note that Salt\(aqs \fBcp\fP module is imported at the top of the file, along with all
+of the other necessary testing imports. The \fBget_file\fP function is then called
+directed in the testing function, instead of using the \fBrun_function\fP method as
+the integration test examples do above.
+.sp
+The call to \fBcp.get_file\fP returns an empty string when a \fBhash_file\fP isn\(aqt found.
+Therefore, the example above is a good illustration of a unit test "blocking
+the exits" via the \fB@patch\fP decorator, as well as testing logic via asserting
+against the \fBreturn\fP statement in the \fBif\fP clause.
+.sp
+There are more examples of writing unit tests of varying complexities available
+in the following docs:
+.INDENT 0.0
+.IP \(bu 2
+Simple Unit Test Example
+.IP \(bu 2
+Complete Unit Test Example
+.IP \(bu 2
+Complex Unit Test Example
+.UNINDENT
+.sp
+\fBNOTE:\fP
+.INDENT 0.0
+.INDENT 3.5
+Considerable care should be made to ensure that you\(aqre testing something
+useful in your test functions. It is very easy to fall into a situation
+where you have mocked so much of the original function that the test
+results in only asserting against the data you have provided. This results
+in a poor and fragile unit test.
+.UNINDENT
+.UNINDENT
+.SS Checking for Log Messages
+.sp
+To test to see if a given log message has been emitted, the following pattern
+can be used
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+# Import logging handler
+from tests.support.helpers import TestsLoggingHandler
+
+# .. inside test
+with TestsLoggingHandler() as handler:
+ for message in handler.messages:
+ if message.startswith(\(aqERROR: This is the error message we seek\(aq):
+ break
+ else:
+ raise AssertionError(\(aqDid not find error message\(aq)
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.SS Automated Test Runs
+.sp
+SaltStack maintains a Jenkins server which can be viewed at
+\fI\%https://jenkins.saltstack.com\fP\&. The tests executed from this Jenkins server
+create fresh virtual machines for each test run, then execute the destructive
+tests on the new, clean virtual machine. This allows for the execution of tests
+across supported platforms.
+.SS Additional Testing Documentation
+.sp
+In addition to this tutorial, there are some other helpful resources and documentation
+that go into more depth on Salt\(aqs test runner, writing tests for Salt code, and general
+Python testing documentation. Please see the follow references for more information:
+.INDENT 0.0
+.IP \(bu 2
+Salt\(aqs Test Suite Documentation
+.IP \(bu 2
+Integration Tests
+.IP \(bu 2
+Unit Tests
+.IP \(bu 2
+\fI\%MagicMock\fP
+.IP \(bu 2
+\fI\%Python Unittest\fP
+.IP \(bu 2
+\fI\%Python\(aqs Assert Functions\fP
+.UNINDENT
+.SS Troubleshooting
+.sp
+The intent of the troubleshooting section is to introduce solutions to a
+number of common issues encountered by users and the tools that are available
+to aid in developing States and Salt code.
+.SS Troubleshooting the Salt Master
+.sp
+If your Salt master is having issues such as minions not returning data, slow
+execution times, or a variety of other issues, the following links contain
+details on troubleshooting the most common issues encountered:
+.SS Troubleshooting the Salt Master
+.SS Running in the Foreground
+.sp
+A great deal of information is available via the debug logging system, if you
+are having issues with minions connecting or not starting run the master in
+the foreground:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+# salt\-master \-l debug
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Anyone wanting to run Salt daemons via a process supervisor such as \fI\%monit\fP,
+\fI\%runit\fP, or \fI\%supervisord\fP, should omit the \fB\-d\fP argument to the daemons and
+run them in the foreground.
+.SS What Ports does the Master Need Open?
+.sp
+For the master, TCP ports 4505 and 4506 need to be open. If you\(aqve put both
+your Salt master and minion in debug mode and don\(aqt see an acknowledgment
+that your minion has connected, it could very well be a firewall interfering
+with the connection. See our firewall configuration page for help opening the firewall on various
+platforms.
+.sp
+If you\(aqve opened the correct TCP ports and still aren\(aqt seeing connections,
+check that no additional access control system such as \fI\%SELinux\fP or
+\fI\%AppArmor\fP is blocking Salt.
+.SS Too many open files
+.sp
+The salt\-master needs at least 2 sockets per host that connects to it, one for
+the Publisher and one for response port. Thus, large installations may, upon
+scaling up the number of minions accessing a given master, encounter:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+12:45:29,289 [salt.master ][INFO ] Starting Salt worker process 38
+Too many open files
+sock != \-1 (tcp_listener.cpp:335)
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+The solution to this would be to check the number of files allowed to be
+opened by the user running salt\-master (root by default):
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+[root@salt\-master ~]# ulimit \-n
+1024
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+If this value is not equal to at least twice the number of minions, then it
+will need to be raised. For example, in an environment with 1800 minions, the
+\fBnofile\fP limit should be set to no less than 3600. This can be done by
+creating the file \fB/etc/security/limits.d/99\-salt.conf\fP, with the following
+contents:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+root hard nofile 4096
+root soft nofile 4096
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Replace \fBroot\fP with the user under which the master runs, if different.
+.sp
+If your master does not have an \fB/etc/security/limits.d\fP directory, the lines
+can simply be appended to \fB/etc/security/limits.conf\fP\&.
+.sp
+As with any change to resource limits, it is best to stay logged into your
+current shell and open another shell to run \fBulimit \-n\fP again and verify that
+the changes were applied correctly. Additionally, if your master is running
+upstart, it may be necessary to specify the \fBnofile\fP limit in
+\fB/etc/default/salt\-master\fP if upstart isn\(aqt respecting your resource limits:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+limit nofile 4096 4096
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+\fBNOTE:\fP
+.INDENT 0.0
+.INDENT 3.5
+The above is simply an example of how to set these values, and you may
+wish to increase them even further if your Salt master is doing more than
+just running Salt.
+.UNINDENT
+.UNINDENT
+.SS Salt Master Stops Responding
+.sp
+There are known bugs with ZeroMQ versions less than 2.1.11 which can cause the
+Salt master to not respond properly. If you\(aqre running a ZeroMQ version greater
+than or equal to 2.1.9, you can work around the bug by setting the sysctls
+\fBnet.core.rmem_max\fP and \fBnet.core.wmem_max\fP to 16777216. Next, set the third
+field in \fBnet.ipv4.tcp_rmem\fP and \fBnet.ipv4.tcp_wmem\fP to at least 16777216.
+.sp
+You can do it manually with something like:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+# echo 16777216 > /proc/sys/net/core/rmem_max
+# echo 16777216 > /proc/sys/net/core/wmem_max
+# echo "4096 87380 16777216" > /proc/sys/net/ipv4/tcp_rmem
+# echo "4096 87380 16777216" > /proc/sys/net/ipv4/tcp_wmem
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Or with the following Salt state:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+net.core.rmem_max:
+ sysctl:
+ \- present
+ \- value: 16777216
+
+net.core.wmem_max:
+ sysctl:
+ \- present
+ \- value: 16777216
+
+net.ipv4.tcp_rmem:
+ sysctl:
+ \- present
+ \- value: 4096 87380 16777216
+
+net.ipv4.tcp_wmem:
+ sysctl:
+ \- present
+ \- value: 4096 87380 16777216
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.SS Live Python Debug Output
+.sp
+If the master seems to be unresponsive, a SIGUSR1 can be passed to the
+salt\-master threads to display what piece of code is executing. This debug
+information can be invaluable in tracking down bugs.
+.sp
+To pass a SIGUSR1 to the master, first make sure the minion is running in the
+foreground. Stop the service if it is running as a daemon, and start it in the
+foreground like so:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+# salt\-master \-l debug
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Then pass the signal to the master when it seems to be unresponsive:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+# killall \-SIGUSR1 salt\-master
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+When filing an issue or sending questions to the mailing list for a problem
+with an unresponsive daemon, be sure to include this information if possible.
+.SS Live Salt\-Master Profiling
+.sp
+When faced with performance problems one can turn on master process profiling by
+sending it SIGUSR2.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+# killall \-SIGUSR2 salt\-master
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+This will activate \fByappi\fP profiler inside salt\-master code, then after some
+time one must send SIGUSR2 again to stop profiling and save results to file. If
+run in foreground salt\-master will report filename for the results, which are
+usually located under \fB/tmp\fP on Unix\-based OSes and \fBc:\etemp\fP on windows.
+.sp
+Results can then be analyzed with \fI\%kcachegrind\fP or similar tool.
+.SS Commands Time Out or Do Not Return Output
+.sp
+Depending on your OS (this is most common on Ubuntu due to apt\-get) you may
+sometimes encounter times where a \fBstate.apply\fP, or other long running commands do not return
+output.
+.sp
+By default the timeout is set to 5 seconds. The timeout value can easily be
+increased by modifying the \fBtimeout\fP line within your \fB/etc/salt/master\fP
+configuration file.
+.sp
+Having keys accepted for Salt minions that no longer exist or are not reachable
+also increases the possibility of timeouts, since the Salt master waits for
+those systems to return command results.
+.SS Passing the \-c Option to Salt Returns a Permissions Error
+.sp
+Using the \fB\-c\fP option with the Salt command modifies the configuration
+directory. When the configuration file is read it will still base data off of
+the \fBroot_dir\fP setting. This can result in unintended behavior if you are
+expecting files such as \fB/etc/salt/pki\fP to be pulled from the location
+specified with \fB\-c\fP\&. Modify the \fBroot_dir\fP setting to address this
+behavior.
+.SS Salt Master Doesn\(aqt Return Anything While Running jobs
+.sp
+When a command being run via Salt takes a very long time to return
+(package installations, certain scripts, etc.) the master may drop you back
+to the shell. In most situations the job is still running but Salt has
+exceeded the set timeout before returning. Querying the job queue will
+provide the data of the job but is inconvenient. This can be resolved by
+either manually using the \fB\-t\fP option to set a longer timeout when running
+commands (by default it is 5 seconds) or by modifying the master
+configuration file: \fB/etc/salt/master\fP and setting the \fBtimeout\fP value to
+change the default timeout for all commands, and then restarting the
+salt\-master service.
+.SS Salt Master Auth Flooding
+.sp
+In large installations, care must be taken not to overwhealm the master with
+authentication requests. Several options can be set on the master which
+mitigate the chances of an authentication flood from causing an interruption in
+service.
+.sp
+\fBNOTE:\fP
+.INDENT 0.0
+.INDENT 3.5
+recon_default:
+.sp
+The average number of seconds to wait between reconnection attempts.
+.INDENT 0.0
+.TP
+.B recon_max:
+The maximum number of seconds to wait between reconnection attempts.
+.TP
+.B recon_randomize:
+A flag to indicate whether the recon_default value should be randomized.
+.TP
+.B acceptance_wait_time:
+The number of seconds to wait for a reply to each authentication request.
+.TP
+.B random_reauth_delay:
+The range of seconds across which the minions should attempt to randomize
+authentication attempts.
+.TP
+.B auth_timeout:
+The total time to wait for the authentication process to complete, regardless
+of the number of attempts.
+.UNINDENT
+.UNINDENT
+.UNINDENT
+.SS Running states locally
+.sp
+To debug the states, you can use call locally.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+salt\-call \-l trace \-\-local state.highstate
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+The top.sls file is used to map what SLS modules get loaded onto what minions via the state system.
+.sp
+It is located in the file defined in the \fBfile_roots\fP variable of the salt master
+configuration file which is defined by found in \fBCONFIG_DIR/master\fP, normally \fB/etc/salt/master\fP
+.sp
+The default configuration for the \fBfile_roots\fP is:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+file_roots:
+ base:
+ \- /srv/salt
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+So the top file is defaulted to the location \fB/srv/salt/top.sls\fP
+.SS Salt Master Umask
+.sp
+The salt master uses a cache to track jobs as they are published and returns come back.
+The recommended umask for a salt\-master is \fI022\fP, which is the default for most users
+on a system. Incorrect umasks can result in permission\-denied errors when the master
+tries to access files in its cache.
+.SS Troubleshooting the Salt Minion
+.sp
+In the event that your Salt minion is having issues, a variety of solutions
+and suggestions are available. Please refer to the following links for more information:
+.SS Troubleshooting the Salt Minion
+.SS Running in the Foreground
+.sp
+A great deal of information is available via the debug logging system, if you
+are having issues with minions connecting or not starting run the minion in
+the foreground:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+# salt\-minion \-l debug
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Anyone wanting to run Salt daemons via a process supervisor such as \fI\%monit\fP,
+\fI\%runit\fP, or \fI\%supervisord\fP, should omit the \fB\-d\fP argument to the daemons and
+run them in the foreground.
+.SS What Ports does the Minion Need Open?
+.sp
+No ports need to be opened on the minion, as it makes outbound connections to
+the master. If you\(aqve put both your Salt master and minion in debug mode and
+don\(aqt see an acknowledgment that your minion has connected, it could very well
+be a firewall interfering with the connection. See our firewall
+configuration page for help opening the firewall
+on various platforms.
+.sp
+If you have netcat installed, you can check port connectivity from the minion
+with the \fBnc\fP command:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+$ nc \-v \-z salt.master.ip.addr 4505
+Connection to salt.master.ip.addr 4505 port [tcp/unknown] succeeded!
+$ nc \-v \-z salt.master.ip.addr 4506
+Connection to salt.master.ip.addr 4506 port [tcp/unknown] succeeded!
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+The \fI\%Nmap\fP utility can also be used to check if these ports are open:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+# nmap \-sS \-q \-p 4505\-4506 salt.master.ip.addr
+
+Starting Nmap 6.40 ( http://nmap.org ) at 2013\-12\-29 19:44 CST
+Nmap scan report for salt.master.ip.addr (10.0.0.10)
+Host is up (0.0026s latency).
+PORT STATE SERVICE
+4505/tcp open unknown
+4506/tcp open unknown
+MAC Address: 00:11:22:AA:BB:CC (Intel)
+
+Nmap done: 1 IP address (1 host up) scanned in 1.64 seconds
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+If you\(aqve opened the correct TCP ports and still aren\(aqt seeing connections,
+check that no additional access control system such as \fI\%SELinux\fP or
+\fI\%AppArmor\fP is blocking Salt. Tools like \fI\%tcptraceroute\fP can also be used
+to determine if an intermediate device or firewall is blocking the needed
+TCP ports.
+.SS Using salt\-call
+.sp
+The \fBsalt\-call\fP command was originally developed for aiding in the
+development of new Salt modules. Since then, many applications have been
+developed for running any Salt module locally on a minion. These range from the
+original intent of salt\-call (development assistance), to gathering more
+verbose output from calls like \fBstate.apply\fP\&.
+.sp
+When initially creating your state tree, it is generally recommended to invoke
+highstates by running \fBstate.apply\fP directly
+from the minion with \fBsalt\-call\fP, rather than remotely from the master. This
+displays far more information about the execution than calling it remotely. For
+even more verbosity, increase the loglevel using the \fB\-l\fP argument:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+# salt\-call \-l debug state.apply
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+The main difference between using \fBsalt\fP and using \fBsalt\-call\fP is that
+\fBsalt\-call\fP is run from the minion, and it only runs the selected function on
+that minion. By contrast, \fBsalt\fP is run from the master, and requires you to
+specify the minions on which to run the command using salt\(aqs targeting
+system\&.
+.SS Live Python Debug Output
+.sp
+If the minion seems to be unresponsive, a SIGUSR1 can be passed to the process
+to display what piece of code is executing. This debug information can be
+invaluable in tracking down bugs.
+.sp
+To pass a SIGUSR1 to the minion, first make sure the minion is running in the
+foreground. Stop the service if it is running as a daemon, and start it in the
+foreground like so:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+# salt\-minion \-l debug
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Then pass the signal to the minion when it seems to be unresponsive:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+# killall \-SIGUSR1 salt\-minion
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+When filing an issue or sending questions to the mailing list for a problem
+with an unresponsive daemon, be sure to include this information if possible.
+.SS Multiprocessing in Execution Modules
+.sp
+As is outlined in github issue #6300, Salt cannot use python\(aqs multiprocessing
+pipes and queues from execution modules. Multiprocessing from the execution
+modules is perfectly viable, it is just necessary to use Salt\(aqs event system
+to communicate back with the process.
+.sp
+The reason for this difficulty is that python attempts to pickle all objects in
+memory when communicating, and it cannot pickle function objects. Since the
+Salt loader system creates and manages function objects this causes the pickle
+operation to fail.
+.SS Salt Minion Doesn\(aqt Return Anything While Running Jobs Locally
+.sp
+When a command being run via Salt takes a very long time to return
+(package installations, certain scripts, etc.) the minion may drop you back
+to the shell. In most situations the job is still running but Salt has
+exceeded the set timeout before returning. Querying the job queue will
+provide the data of the job but is inconvenient. This can be resolved by
+either manually using the \fB\-t\fP option to set a longer timeout when running
+commands (by default it is 5 seconds) or by modifying the minion
+configuration file: \fB/etc/salt/minion\fP and setting the \fBtimeout\fP value to
+change the default timeout for all commands, and then restarting the
+salt\-minion service.
+.sp
+\fBNOTE:\fP
+.INDENT 0.0
+.INDENT 3.5
+Modifying the minion timeout value is not required when running commands
+from a Salt Master. It is only required when running commands locally on
+the minion.
+.UNINDENT
+.UNINDENT
+.SS Running in the Foreground
+.sp
+A great deal of information is available via the debug logging system, if you
+are having issues with minions connecting or not starting run the minion and/or
+master in the foreground:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+salt\-master \-l debug
+salt\-minion \-l debug
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Anyone wanting to run Salt daemons via a process supervisor such as \fI\%monit\fP,
+\fI\%runit\fP, or \fI\%supervisord\fP, should omit the \fB\-d\fP argument to the daemons and
+run them in the foreground.
+.SS What Ports do the Master and Minion Need Open?
+.sp
+No ports need to be opened up on each minion. For the master, TCP ports 4505
+and 4506 need to be open. If you\(aqve put both your Salt master and minion in
+debug mode and don\(aqt see an acknowledgment that your minion has connected,
+it could very well be a firewall.
+.sp
+You can check port connectivity from the minion with the nc command:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+nc \-v \-z salt.master.ip 4505
+nc \-v \-z salt.master.ip 4506
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+There is also a firewall configuration
+document that might help as well.
+.sp
+If you\(aqve enabled the right TCP ports on your operating system or Linux
+distribution\(aqs firewall and still aren\(aqt seeing connections, check that no
+additional access control system such as \fI\%SELinux\fP or \fI\%AppArmor\fP is blocking
+Salt.
+.SS Using salt\-call
+.sp
+The \fBsalt\-call\fP command was originally developed for aiding in the development
+of new Salt modules. Since then, many applications have been developed for
+running any Salt module locally on a minion. These range from the original
+intent of salt\-call, development assistance, to gathering more verbose output
+from calls like \fBstate.apply\fP\&.
+.sp
+When initially creating your state tree, it is generally recommended to invoke
+\fBstate.apply\fP directly from the minion with
+\fBsalt\-call\fP, rather than remotely from the master. This displays far more
+information about the execution than calling it remotely. For even more
+verbosity, increase the loglevel using the \fB\-l\fP argument:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+salt\-call \-l debug state.apply
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+The main difference between using \fBsalt\fP and using \fBsalt\-call\fP is that
+\fBsalt\-call\fP is run from the minion, and it only runs the selected function on
+that minion. By contrast, \fBsalt\fP is run from the master, and requires you to
+specify the minions on which to run the command using salt\(aqs targeting
+system\&.
+.SS Too many open files
+.sp
+The salt\-master needs at least 2 sockets per host that connects to it, one for
+the Publisher and one for response port. Thus, large installations may, upon
+scaling up the number of minions accessing a given master, encounter:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+12:45:29,289 [salt.master ][INFO ] Starting Salt worker process 38
+Too many open files
+sock != \-1 (tcp_listener.cpp:335)
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+The solution to this would be to check the number of files allowed to be
+opened by the user running salt\-master (root by default):
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+[root@salt\-master ~]# ulimit \-n
+1024
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+And modify that value to be at least equal to the number of minions x 2.
+This setting can be changed in limits.conf as the nofile value(s),
+and activated upon new a login of the specified user.
+.sp
+So, an environment with 1800 minions, would need 1800 x 2 = 3600 as a minimum.
+.SS Salt Master Stops Responding
+.sp
+There are known bugs with ZeroMQ versions less than 2.1.11 which can cause the
+Salt master to not respond properly. If you\(aqre running a ZeroMQ version greater
+than or equal to 2.1.9, you can work around the bug by setting the sysctls
+\fBnet.core.rmem_max\fP and \fBnet.core.wmem_max\fP to 16777216. Next, set the third
+field in \fBnet.ipv4.tcp_rmem\fP and \fBnet.ipv4.tcp_wmem\fP to at least 16777216.
+.sp
+You can do it manually with something like:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+# echo 16777216 > /proc/sys/net/core/rmem_max
+# echo 16777216 > /proc/sys/net/core/wmem_max
+# echo "4096 87380 16777216" > /proc/sys/net/ipv4/tcp_rmem
+# echo "4096 87380 16777216" > /proc/sys/net/ipv4/tcp_wmem
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Or with the following Salt state:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+net.core.rmem_max:
+ sysctl:
+ \- present
+ \- value: 16777216
+
+net.core.wmem_max:
+ sysctl:
+ \- present
+ \- value: 16777216
+
+net.ipv4.tcp_rmem:
+ sysctl:
+ \- present
+ \- value: 4096 87380 16777216
+
+net.ipv4.tcp_wmem:
+ sysctl:
+ \- present
+ \- value: 4096 87380 16777216
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.SS Salt and SELinux
+.sp
+Currently there are no SELinux policies for Salt. For the most part Salt runs
+without issue when SELinux is running in Enforcing mode. This is because when
+the minion executes as a daemon the type context is changed to \fBinitrc_t\fP\&.
+The problem with SELinux arises when using salt\-call or running the minion in
+the foreground, since the type context stays \fBunconfined_t\fP\&.
+.sp
+This problem is generally manifest in the rpm install scripts when using the
+pkg module. Until a full SELinux Policy is available for Salt the solution
+to this issue is to set the execution context of \fBsalt\-call\fP and
+\fBsalt\-minion\fP to rpm_exec_t:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+# CentOS 5 and RHEL 5:
+chcon \-t system_u:system_r:rpm_exec_t:s0 /usr/bin/salt\-minion
+chcon \-t system_u:system_r:rpm_exec_t:s0 /usr/bin/salt\-call
+
+# CentOS 6 and RHEL 6:
+chcon system_u:object_r:rpm_exec_t:s0 /usr/bin/salt\-minion
+chcon system_u:object_r:rpm_exec_t:s0 /usr/bin/salt\-call
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+This works well, because the \fBrpm_exec_t\fP context has very broad control over
+other types.
+.SS Red Hat Enterprise Linux 5
+.sp
+Salt requires Python 2.6 or 2.7. Red Hat Enterprise Linux 5 and its variants
+come with Python 2.4 installed by default. When installing on RHEL 5 from the
+\fI\%EPEL repository\fP this is handled for you. But, if you run Salt from git, be
+advised that its dependencies need to be installed from EPEL and that Salt
+needs to be run with the \fBpython26\fP executable.
+.SS Common YAML Gotchas
+.sp
+An extensive list of YAML idiosyncrasies has been compiled:
+.SS YAML Idiosyncrasies
+.sp
+One of Salt\(aqs strengths, the use of existing serialization systems for
+representing SLS data, can also backfire. \fI\%YAML\fP is a general purpose system
+and there are a number of things that would seem to make sense in an sls
+file that cause YAML issues. It is wise to be aware of these issues. While
+reports or running into them are generally rare they can still crop up at
+unexpected times.
+.SS Spaces vs Tabs
+.sp
+\fI\%YAML uses spaces\fP, period. Do not use tabs in your SLS files! If strange
+errors are coming up in rendering SLS files, make sure to check that
+no tabs have crept in! In Vim, after enabling search highlighting
+with: \fB:set hlsearch\fP, you can check with the following key sequence in
+normal mode(you can hit \fIESC\fP twice to be sure): \fB/\fP, \fICtrl\-v\fP, \fITab\fP, then
+hit \fIEnter\fP\&. Also, you can convert tabs to 2 spaces by these commands in Vim:
+\fB:set tabstop=2 expandtab\fP and then \fB:retab\fP\&.
+.SS Indentation
+.sp
+The suggested syntax for YAML files is to use 2 spaces for indentation,
+but YAML will follow whatever indentation system that the individual file
+uses. Indentation of two spaces works very well for SLS files given the
+fact that the data is uniform and not deeply nested.
+.SS Nested Dictionaries
+.sp
+When dictionaries are nested within other data structures (particularly lists),
+the indentation logic sometimes changes. Examples of where this might happen
+include \fBcontext\fP and \fBdefault\fP options from the \fBfile.managed\fP state:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+/etc/http/conf/http.conf:
+ file:
+ \- managed
+ \- source: salt://apache/http.conf
+ \- user: root
+ \- group: root
+ \- mode: 644
+ \- template: jinja
+ \- context:
+ custom_var: "override"
+ \- defaults:
+ custom_var: "default value"
+ other_var: 123
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Notice that while the indentation is two spaces per level, for the values under
+the \fBcontext\fP and \fBdefaults\fP options there is a four\-space indent. If only
+two spaces are used to indent, then those keys will be considered part of the
+same dictionary that contains the \fBcontext\fP key, and so the data will not be
+loaded correctly. If using a double indent is not desirable, then a
+deeply\-nested dict can be declared with curly braces:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+/etc/http/conf/http.conf:
+ file:
+ \- managed
+ \- source: salt://apache/http.conf
+ \- user: root
+ \- group: root
+ \- mode: 644
+ \- template: jinja
+ \- context:
+ custom_var: "override"
+ \- defaults:
+ custom_var: "default value"
+ other_var: 123
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Here is a more concrete example of how YAML actually handles these
+indentations, using the Python interpreter on the command line:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+>>> import yaml
+>>> yaml.safe_load(\(aq\(aq\(aqmystate:
+\&... file.managed:
+\&... \- context:
+\&... some: var\(aq\(aq\(aq)
+{\(aqmystate\(aq: {\(aqfile.managed\(aq: [{\(aqcontext\(aq: {\(aqsome\(aq: \(aqvar\(aq}}]}}
+>>> yaml.safe_load(\(aq\(aq\(aqmystate:
+\&... file.managed:
+\&... \- context:
+\&... some: var\(aq\(aq\(aq)
+{\(aqmystate\(aq: {\(aqfile.managed\(aq: [{\(aqsome\(aq: \(aqvar\(aq, \(aqcontext\(aq: None}]}}
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Note that in the second example, \fBsome\fP is added as another key in the same
+dictionary, whereas in the first example, it\(aqs the start of a new dictionary.
+That\(aqs the distinction. \fBcontext\fP is a common example because it is a keyword
+arg for many functions, and should contain a dictionary.
+.SS True/False, Yes/No, On/Off
+.sp
+PyYAML will load these values as boolean \fBTrue\fP or \fBFalse\fP\&. Un\-capitalized
+versions will also be loaded as booleans (\fBtrue\fP, \fBfalse\fP, \fByes\fP, \fBno\fP,
+\fBon\fP, and \fBoff\fP). This can be especially problematic when constructing
+Pillar data. Make sure that your Pillars which need to use the string versions
+of these values are enclosed in quotes. Pillars will be parsed twice by salt,
+so you\(aqll need to wrap your values in multiple quotes, including double quotation
+marks (\fB" "\fP) and single quotation marks (\fB\(aq \(aq\fP). Note that spaces are included
+in the quotation type examples for clarity.
+.sp
+Multiple quoting examples looks like this:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+\- \(aq"false"\(aq
+\- "\(aqTrue\(aq"
+\- "\(aqYES\(aq"
+\- \(aq"No"\(aq
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+\fBNOTE:\fP
+.INDENT 0.0
+.INDENT 3.5
+When using multiple quotes in this manner, they must be different. Using \fB"" ""\fP
+or \fB\(aq\(aq \(aq\(aq\fP won\(aqt work in this case (spaces are included in examples for clarity).
+.UNINDENT
+.UNINDENT
+.SS The \(aq%\(aq Sign
+.sp
+The \fI%\fP symbol has a special meaning in YAML, it needs to be passed as a
+string literal:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+cheese:
+ ssh_auth.present:
+ \- user: tbortels
+ \- source: salt://ssh_keys/chease.pub
+ \- config: \(aq%h/.ssh/authorized_keys\(aq
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.SS Time Expressions
+.sp
+PyYAML will load a time expression as the integer value of that, assuming
+\fBHH:MM\fP\&. So for example, \fB12:00\fP is loaded by PyYAML as \fB720\fP\&. An
+excellent explanation for why can be found \fI\%here\fP\&.
+.sp
+To keep time expressions like this from being loaded as integers, always quote
+them.
+.sp
+\fBNOTE:\fP
+.INDENT 0.0
+.INDENT 3.5
+When using a jinja \fBload_yaml\fP map, items must be quoted twice. For
+example:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+{% load_yaml as wsus_schedule %}
+
+FRI_10:
+ time: \(aq"23:00"\(aq
+ day: 6 \- Every Friday
+SAT_10:
+ time: \(aq"06:00"\(aq
+ day: 7 \- Every Saturday
+SAT_20:
+ time: \(aq"14:00"\(aq
+ day: 7 \- Every Saturday
+SAT_30:
+ time: \(aq"22:00"\(aq
+ day: 7 \- Every Saturday
+SUN_10:
+ time: \(aq"06:00"\(aq
+ day: 1 \- Every Sunday
+{% endload %}
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.UNINDENT
+.UNINDENT
+.SS YAML does not like "Double Short Decs"
+.sp
+If I can find a way to make YAML accept "Double Short Decs" then I will, since
+I think that double short decs would be awesome. So what is a "Double Short
+Dec"? It is when you declare a multiple short decs in one ID. Here is a
+standard short dec, it works great:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+vim:
+ pkg.installed
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+The short dec means that there are no arguments to pass, so it is not required
+to add any arguments, and it can save space.
+.sp
+YAML though, gets upset when declaring multiple short decs, for the record...
+.sp
+THIS DOES NOT WORK:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+vim:
+ pkg.installed
+ user.present
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Similarly declaring a short dec in the same ID dec as a standard dec does not
+work either...
+.sp
+ALSO DOES NOT WORK:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+fred:
+ user.present
+ ssh_auth.present:
+ \- name: AAAAB3NzaC...
+ \- user: fred
+ \- enc: ssh\-dss
+ \- require:
+ \- user: fred
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+The correct way is to define them like this:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+vim:
+ pkg.installed: []
+ user.present: []
+
+fred:
+ user.present: []
+ ssh_auth.present:
+ \- name: AAAAB3NzaC...
+ \- user: fred
+ \- enc: ssh\-dss
+ \- require:
+ \- user: fred
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Alternatively, they can be defined the "old way", or with multiple
+"full decs":
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+vim:
+ pkg:
+ \- installed
+ user:
+ \- present
+
+fred:
+ user:
+ \- present
+ ssh_auth:
+ \- present
+ \- name: AAAAB3NzaC...
+ \- user: fred
+ \- enc: ssh\-dss
+ \- require:
+ \- user: fred
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.SS YAML supports only plain ASCII
+.sp
+According to YAML specification, only ASCII characters can be used.
+.sp
+Within double\-quotes, special characters may be represented with C\-style
+escape sequences starting with a backslash ( \e ).
+.sp
+Examples:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+\- micro: "\eu00b5"
+\- copyright: "\eu00A9"
+\- A: "\ex41"
+\- alpha: "\eu0251"
+\- Alef: "\eu05d0"
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+List of usable \fI\%Unicode characters\fP will help you to identify correct numbers.
+.sp
+Python can also be used to discover the Unicode number for a character:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+repr(u"Text with wrong characters i need to figure out")
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+This shell command can find wrong characters in your SLS files:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+find . \-name \(aq*.sls\(aq \-exec grep \-\-color=\(aqauto\(aq \-P \-n \(aq[^\ex00\-\ex7F]\(aq \e{} \e;
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Alternatively you can toggle the \fIyaml_utf8\fP setting in your master configuration
+file. This is still an experimental setting but it should manage the right
+encoding conversion in salt after yaml states compilations.
+.SS Underscores stripped in Integer Definitions
+.sp
+If a definition only includes numbers and underscores, it is parsed by YAML as
+an integer and all underscores are stripped. To ensure the object becomes a
+string, it should be surrounded by quotes. \fI\%More information here\fP\&.
+.sp
+Here\(aqs an example:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+>>> import yaml
+>>> yaml.safe_load(\(aq2013_05_10\(aq)
+20130510
+>>> yaml.safe_load(\(aq"2013_05_10"\(aq)
+\(aq2013_05_10\(aq
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.SS Automatic \fBdatetime\fP conversion
+.sp
+If there is a value in a YAML file formatted \fB2014\-01\-20 14:23:23\fP or
+similar, YAML will automatically convert this to a Python \fBdatetime\fP object.
+These objects are not msgpack serializable, and so may break core salt
+functionality. If values such as these are needed in a salt YAML file
+(specifically a configuration file), they should be formatted with surrounding
+strings to force YAML to serialize them as strings:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+>>> import yaml
+>>> yaml.safe_load(\(aq2014\-01\-20 14:23:23\(aq)
+datetime.datetime(2014, 1, 20, 14, 23, 23)
+>>> yaml.safe_load(\(aq"2014\-01\-20 14:23:23"\(aq)
+\(aq2014\-01\-20 14:23:23\(aq
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Additionally, numbers formatted like \fBXXXX\-XX\-XX\fP will also be converted (or
+YAML will attempt to convert them, and error out if it doesn\(aqt think the date
+is a real one). Thus, for example, if a minion were to have an ID of
+\fB4017\-16\-20\fP the minion would not start because YAML would complain that the
+date was out of range. The workaround is the same, surround the offending
+string with quotes:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+>>> import yaml
+>>> yaml.safe_load(\(aq4017\-16\-20\(aq)
+Traceback (most recent call last):
+ File "", line 1, in
+ File "/usr/local/lib/python2.7/site\-packages/yaml/__init__.py", line 93, in safe_load
+ return load(stream, SafeLoader)
+ File "/usr/local/lib/python2.7/site\-packages/yaml/__init__.py", line 71, in load
+ return loader.get_single_data()
+ File "/usr/local/lib/python2.7/site\-packages/yaml/constructor.py", line 39, in get_single_data
+ return self.construct_document(node)
+ File "/usr/local/lib/python2.7/site\-packages/yaml/constructor.py", line 43, in construct_document
+ data = self.construct_object(node)
+ File "/usr/local/lib/python2.7/site\-packages/yaml/constructor.py", line 88, in construct_object
+ data = constructor(self, node)
+ File "/usr/local/lib/python2.7/site\-packages/yaml/constructor.py", line 312, in construct_yaml_timestamp
+ return datetime.date(year, month, day)
+ValueError: month must be in 1..12
+>>> yaml.safe_load(\(aq"4017\-16\-20"\(aq)
+\(aq4017\-16\-20\(aq
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.SS Keys Limited to 1024 Characters
+.sp
+Simple keys are limited to a single line and cannot be longer that 1024 characters.
+This is a limitation from PyYaml, as seen in a comment in \fI\%PyYAML\(aqs code\fP, and
+applies to anything parsed by YAML in Salt.
+.SS Live Python Debug Output
+.sp
+If the minion or master seems to be unresponsive, a SIGUSR1 can be passed to
+the processes to display where in the code they are running. If encountering a
+situation like this, this debug information can be invaluable. First make
+sure the master of minion are running in the foreground:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+salt\-master \-l debug
+salt\-minion \-l debug
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Then pass the signal to the master or minion when it seems to be unresponsive:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+killall \-SIGUSR1 salt\-master
+killall \-SIGUSR1 salt\-minion
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Also under BSD and macOS in addition to SIGUSR1 signal, debug subroutine set
+up for SIGINFO which has an advantage of being sent by Ctrl+T shortcut.
+.sp
+When filing an issue or sending questions to the mailing list for a problem
+with an unresponsive daemon this information can be invaluable.
+.SS Salt 0.16.x minions cannot communicate with a 0.17.x master
+.sp
+As of release 0.17.1 you can no longer run different versions of Salt on your
+Master and Minion servers. This is due to a protocol change for security
+purposes. The Salt team will continue to attempt to ensure versions are as
+backwards compatible as possible.
+.SS Debugging the Master and Minion
+.sp
+A list of common master and
+minion troubleshooting steps provide a
+starting point for resolving issues you may encounter.
+.SS Frequently Asked Questions
+.SS FAQ
+.INDENT 0.0
+.IP \(bu 2
+\fI\%Frequently Asked Questions\fP
+.INDENT 2.0
+.IP \(bu 2
+\fI\%Is Salt open\-core?\fP
+.IP \(bu 2
+\fI\%I think I found a bug! What should I do?\fP
+.IP \(bu 2
+\fI\%What ports should I open on my firewall?\fP
+.IP \(bu 2
+\fI\%I\(aqm seeing weird behavior (including but not limited to packages not installing their users properly)\fP
+.IP \(bu 2
+\fI\%My script runs every time I run a state.apply. Why?\fP
+.IP \(bu 2
+\fI\%When I run test.ping, why don\(aqt the Minions that aren\(aqt responding return anything? Returning False would be helpful.\fP
+.IP \(bu 2
+\fI\%How does Salt determine the Minion\(aqs id?\fP
+.IP \(bu 2
+\fI\%I\(aqm trying to manage packages/services but I get an error saying that the state is not available. Why?\fP
+.IP \(bu 2
+\fI\%Why aren\(aqt my custom modules/states/etc. available on my Minions?\fP
+.IP \(bu 2
+\fI\%Module X isn\(aqt available, even though the shell command it uses is installed. Why?\fP
+.IP \(bu 2
+\fI\%Can I run different versions of Salt on my Master and Minion?\fP
+.IP \(bu 2
+\fI\%Does Salt support backing up managed files?\fP
+.IP \(bu 2
+\fI\%Is it possible to deploy a file to a specific minion, without other minions having access to it?\fP
+.IP \(bu 2
+\fI\%What is the best way to restart a Salt Minion daemon using Salt after upgrade?\fP
+.INDENT 2.0
+.IP \(bu 2
+\fI\%Upgrade without automatic restart\fP
+.IP \(bu 2
+\fI\%Restart using states\fP
+.IP \(bu 2
+\fI\%Restart using remote executions\fP
+.UNINDENT
+.IP \(bu 2
+\fI\%Salting the Salt Master\fP
+.IP \(bu 2
+\fI\%Is Targeting using Grain Data Secure?\fP
+.IP \(bu 2
+\fI\%Why Did the Value for a Grain Change on Its Own?\fP
+.UNINDENT
+.UNINDENT
+.SS Is Salt open\-core?
+.sp
+No. Salt is 100% committed to being open\-source, including all of our APIs. It
+is developed under the \fI\%Apache 2.0 license\fP, allowing it to be used in both
+open and proprietary projects.
+.sp
+To expand on this a little:
+.sp
+There is much argument over the actual definition of "open core". From our standpoint, Salt is open source because
+.INDENT 0.0
+.IP 1. 3
+It is a standalone product that anyone is free to use.
+.IP 2. 3
+It is developed in the open with contributions accepted from the community for the good of the project.
+.IP 3. 3
+There are no features of Salt itself that are restricted to separate proprietary products distributed by SaltStack, Inc.
+.IP 4. 3
+Because of our Apache 2.0 license, Salt can be used as the foundation for a project or even a proprietary tool.
+.IP 5. 3
+Our APIs are open and documented (any lack of documentation is an oversight as opposed to an intentional decision by SaltStack the company) and available for use by anyone.
+.UNINDENT
+.sp
+SaltStack the company does make proprietary products which use Salt and its libraries, like company is free to do, but we do so via the APIs, NOT by forking Salt and creating a different, closed\-source version of it for paying customers.
+.SS I think I found a bug! What should I do?
+.sp
+The salt\-users mailing list as well as the salt IRC channel can both be helpful
+resources to confirm if others are seeing the issue and to assist with
+immediate debugging.
+.sp
+To report a bug to the Salt project, please follow the instructions in
+reporting a bug\&.
+.SS What ports should I open on my firewall?
+.sp
+Minions need to be able to connect to the Master on TCP ports 4505 and 4506.
+Minions do not need any inbound ports open. More detailed information on
+firewall settings can be found here\&.
+.SS I\(aqm seeing weird behavior (including but not limited to packages not installing their users properly)
+.sp
+This is often caused by SELinux. Try disabling SELinux or putting it in
+permissive mode and see if the weird behavior goes away.
+.SS My script runs every time I run a \fIstate.apply\fP\&. Why?
+.sp
+You are probably using \fBcmd.run\fP rather than
+\fBcmd.wait\fP\&. A \fBcmd.wait\fP state will only run when there has been a change in a
+state that it is watching.
+.sp
+A \fBcmd.run\fP state will run the corresponding command
+\fIevery time\fP (unless it is prevented from running by the \fBunless\fP or \fBonlyif\fP
+arguments).
+.sp
+More details can be found in the documentation for the \fBcmd\fP states.
+.SS When I run \fItest.ping\fP, why don\(aqt the Minions that aren\(aqt responding return anything? Returning \fBFalse\fP would be helpful.
+.sp
+When you run \fItest.ping\fP the Master tells Minions to run commands/functions,
+and listens for the return data, printing it to the screen when it is received.
+If it doesn\(aqt receive anything back, it doesn\(aqt have anything to display for
+that Minion.
+.sp
+There are a couple options for getting information on Minions that are not
+responding. One is to use the verbose (\fB\-v\fP) option when you run salt
+commands, as it will display "Minion did not return" for any Minions which time
+out.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+salt \-v \(aq*\(aq pkg.install zsh
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Another option is to use the \fBmanage.down\fP
+runner:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+salt\-run manage.down
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Also, if the Master is under heavy load, it is possible that the CLI will exit
+without displaying return data for all targeted Minions. However, this doesn\(aqt
+mean that the Minions did not return; this only means that the Salt CLI timed
+out waiting for a response. Minions will still send their return data back to
+the Master once the job completes. If any expected Minions are missing from the
+CLI output, the \fBjobs.list_jobs\fP runner can
+be used to show the job IDs of the jobs that have been run, and the
+\fBjobs.lookup_jid\fP runner can be used to get
+the return data for that job.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+salt\-run jobs.list_jobs
+salt\-run jobs.lookup_jid 20130916125524463507
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+If you find that you are often missing Minion return data on the CLI, only to
+find it with the jobs runners, then this may be a sign that the
+\fBworker_threads\fP value may need to be increased in the master
+config file. Additionally, running your Salt CLI commands with the \fB\-t\fP
+option will make Salt wait longer for the return data before the CLI command
+exits. For instance, the below command will wait up to 60 seconds for the
+Minions to return:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+salt \-t 60 \(aq*\(aq test.ping
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.SS How does Salt determine the Minion\(aqs id?
+.sp
+If the Minion id is not configured explicitly (using the \fBid\fP
+parameter), Salt will determine the id based on the hostname. Exactly how this
+is determined varies a little between operating systems and is described in
+detail here\&.
+.SS I\(aqm trying to manage packages/services but I get an error saying that the state is not available. Why?
+.sp
+Salt detects the Minion\(aqs operating system and assigns the correct package or
+service management module based on what is detected. However, for certain custom
+spins and OS derivatives this detection fails. In cases like this, an issue
+should be opened on our \fI\%tracker\fP, with the following information:
+.INDENT 0.0
+.IP 1. 3
+The output of the following command:
+.INDENT 3.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+salt grains.items | grep os
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.IP 2. 3
+The contents of \fB/etc/lsb\-release\fP, if present on the Minion.
+.UNINDENT
+.SS Why aren\(aqt my custom modules/states/etc. available on my Minions?
+.sp
+Custom modules are synced to Minions when
+\fBsaltutil.sync_modules\fP,
+or \fBsaltutil.sync_all\fP is run.
+.sp
+Similarly, custom states are synced to Minions when \fBsaltutil.sync_states\fP, or \fBsaltutil.sync_all\fP is run.
+.sp
+They are both also synced when a highstate is
+triggered.
+.sp
+As of the Fluorine release, as well as 2017.7.7 and 2018.3.2 in their
+respective release cycles, the \fBsync\fP argument to \fBstate.apply\fP/\fBstate.sls\fP can
+be used to sync custom types when running individual SLS files.
+.sp
+Other custom types (renderers, outputters, etc.) have similar behavior, see the
+documentation for the \fBsaltutil\fP module for more
+information.
+.sp
+This reactor example can be used to automatically
+sync custom types when the minion connects to the master, to help with this
+chicken\-and\-egg issue.
+.SS Module \fBX\fP isn\(aqt available, even though the shell command it uses is installed. Why?
+.sp
+This is most likely a PATH issue. Did you custom\-compile the software which the
+module requires? RHEL/CentOS/etc. in particular override the root user\(aqs path
+in \fB/etc/init.d/functions\fP, setting it to \fB/sbin:/usr/sbin:/bin:/usr/bin\fP,
+making software installed into \fB/usr/local/bin\fP unavailable to Salt when the
+Minion is started using the initscript. In version 2014.1.0, Salt will have a
+better solution for these sort of PATH\-related issues, but recompiling the
+software to install it into a location within the PATH should resolve the
+issue in the meantime. Alternatively, you can create a symbolic link within the
+PATH using a \fBfile.symlink\fP state.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+/usr/bin/foo:
+ file.symlink:
+ \- target: /usr/local/bin/foo
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.SS Can I run different versions of Salt on my Master and Minion?
+.sp
+This depends on the versions. In general, it is recommended that Master and
+Minion versions match.
+.sp
+When upgrading Salt, the master(s) should always be upgraded first. Backwards
+compatibility for minions running newer versions of salt than their masters is
+not guaranteed.
+.sp
+Whenever possible, backwards compatibility between new masters
+and old minions will be preserved. Generally, the only exception to this
+policy is in case of a security vulnerability.
+.sp
+Recent examples of backwards compatibility breakage include the 0.17.1 release
+(where all backwards compatibility was broken due to a security fix), and the
+2014.1.0 release (which retained compatibility between 2014.1.0 masters and
+0.17 minions, but broke compatibility for 2014.1.0 minions and older masters).
+.SS Does Salt support backing up managed files?
+.sp
+Yes. Salt provides an easy to use addition to your file.managed states that
+allow you to back up files via backup_mode,
+backup_mode can be configured on a per state basis, or in the minion config
+(note that if set in the minion config this would simply be the default
+method to use, you still need to specify that the file should be backed up!).
+.SS Is it possible to deploy a file to a specific minion, without other minions having access to it?
+.sp
+The Salt fileserver does not yet support access control, but it is still
+possible to do this. As of Salt 2015.5.0, the
+\fBfile_tree\fP external pillar is available, and
+allows the contents of a file to be loaded as Pillar data. This external pillar
+is capable of assigning Pillar values both to individual minions, and to
+nodegroups\&. See the \fBdocumentation\fP for details on how to set this up.
+.sp
+Once the external pillar has been set up, the data can be pushed to a minion
+via a \fBfile.managed\fP state, using the
+\fBcontents_pillar\fP argument:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+/etc/my_super_secret_file:
+ file.managed:
+ \- user: secret
+ \- group: secret
+ \- mode: 600
+ \- contents_pillar: secret_files:my_super_secret_file
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+In this example, the source file would be located in a directory called
+\fBsecret_files\fP underneath the file_tree path for the minion. The syntax for
+specifying the pillar variable is the same one used for \fBpillar.get\fP, with a colon representing a nested dictionary.
+.sp
+\fBWARNING:\fP
+.INDENT 0.0
+.INDENT 3.5
+Deploying binary contents using the \fBfile.managed\fP state is only supported in Salt 2015.8.4 and
+newer.
+.UNINDENT
+.UNINDENT
+.SS What is the best way to restart a Salt Minion daemon using Salt after upgrade?
+.sp
+Updating the \fBsalt\-minion\fP package requires a restart of the \fBsalt\-minion\fP
+service. But restarting the service while in the middle of a state run
+interrupts the process of the Minion running states and sending results back to
+the Master. A common way to workaround that is to schedule restarting the
+Minion service in the background by issuing a \fBsalt\-call\fP command calling
+\fBservice.restart\fP function. This prevents the Minion being disconnected from
+the Master immediately. Otherwise you would get
+\fBMinion did not return. [Not connected]\fP message as the result of a state run.
+.SS Upgrade without automatic restart
+.sp
+Doing the Minion upgrade seems to be a simplest state in your SLS file at
+first. But the operating systems such as Debian GNU/Linux, Ubuntu and their
+derivatives start the service after the package installation by default.
+To prevent this, we need to create policy layer which will prevent the Minion
+service to restart right after the upgrade:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+{%\- if grains[\(aqos_family\(aq] == \(aqDebian\(aq %}
+
+Disable starting services:
+ file.managed:
+ \- name: /usr/sbin/policy\-rc.d
+ \- user: root
+ \- group: root
+ \- mode: 0755
+ \- contents:
+ \- \(aq#!/bin/sh\(aq
+ \- exit 101
+ # do not touch if already exists
+ \- replace: False
+ \- prereq:
+ \- pkg: Upgrade Salt Minion
+
+{%\- endif %}
+
+Upgrade Salt Minion:
+ pkg.installed:
+ \- name: salt\-minion
+ \- version: 2016.11.3{% if grains[\(aqos_family\(aq] == \(aqDebian\(aq %}+ds\-1{% endif %}
+ \- order: last
+
+Enable Salt Minion:
+ service.enabled:
+ \- name: salt\-minion
+ \- require:
+ \- pkg: Upgrade Salt Minion
+
+{%\- if grains[\(aqos_family\(aq] == \(aqDebian\(aq %}
+
+Enable starting services:
+ file.absent:
+ \- name: /usr/sbin/policy\-rc.d
+ \- onchanges:
+ \- pkg: Upgrade Salt Minion
+
+{%\- endif %}
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.SS Restart using states
+.sp
+Now we can apply the workaround to restart the Minion in reliable way.
+The following example works on UNIX\-like operating systems:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+{%\- if grains[\(aqos\(aq] != \(aqWindows\(aq %}
+Restart Salt Minion:
+ cmd.run:
+ \- name: \(aqsalt\-call service.restart salt\-minion\(aq
+ \- bg: True
+ \- onchanges:
+ \- pkg: Upgrade Salt Minion
+{%\- endif %}
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Note that restarting the \fBsalt\-minion\fP service on Windows operating systems is
+not always necessary when performing an upgrade. The installer stops the
+\fBsalt\-minion\fP service, removes it, deletes the contents of the \fB\esalt\ebin\fP
+directory, installs the new code, re\-creates the \fBsalt\-minion\fP service, and
+starts it (by default). The restart step \fBwould\fP be necessary during the
+upgrade process, however, if the minion config was edited after the upgrade or
+installation. If a minion restart is necessary, the state above can be edited
+as follows:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+Restart Salt Minion:
+ cmd.run:
+{%\- if grains[\(aqkernel\(aq] == \(aqWindows\(aq %}
+ \- name: \(aqC:\esalt\esalt\-call.bat service.restart salt\-minion\(aq
+{%\- else %}
+ \- name: \(aqsalt\-call service.restart salt\-minion\(aq
+{%\- endif %}
+ \- bg: True
+ \- onchanges:
+ \- pkg: Upgrade Salt Minion
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+However, it requires more advanced tricks to upgrade from legacy version of
+Salt (before \fB2016.3.0\fP) on UNIX\-like operating systems, where executing
+commands in the background is not supported. You also may need to schedule
+restarting the Minion service using masterless mode after all other states have been applied for Salt
+versions earlier than \fB2016.11.0\fP\&. This allows the Minion to keep the
+connection to the Master alive for being able to report the final results back
+to the Master, while the service is restarting in the background. This state
+should run last or watch for the \fBpkg\fP state changes:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+Restart Salt Minion:
+ cmd.run:
+{%\- if grains[\(aqkernel\(aq] == \(aqWindows\(aq %}
+ \- name: \(aqstart powershell "Restart\-Service \-Name salt\-minion"\(aq
+{%\- else %}
+ # fork and disown the process
+ \- name: |\-
+ exec 0>&\- # close stdin
+ exec 1>&\- # close stdout
+ exec 2>&\- # close stderr
+ nohup salt\-call \-\-local service.restart salt\-minion &
+{%\- endif %}
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.SS Restart using remote executions
+.sp
+Restart the Minion from the command line:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+salt \-G kernel:Windows cmd.run_bg \(aqC:\esalt\esalt\-call.bat service.restart salt\-minion\(aq
+salt \-C \(aqnot G@kernel:Windows\(aq cmd.run_bg \(aqsalt\-call service.restart salt\-minion\(aq
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.SS Salting the Salt Master
+.sp
+In order to configure a master server via states, the Salt master can also be
+"salted" in order to enforce state on the Salt master as well as the Salt
+minions. Salting the Salt master requires a Salt minion to be installed on
+the same machine as the Salt master. Once the Salt minion is installed, the
+minion configuration file must be pointed to the local Salt master:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+master: 127.0.0.1
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Once the Salt master has been "salted" with a Salt minion, it can be targeted
+just like any other minion. If the minion on the salted master is running, the
+minion can be targeted via any usual \fBsalt\fP command. Additionally, the
+\fBsalt\-call\fP command can execute operations to enforce state on the salted
+master without requiring the minion to be running.
+.sp
+More information about salting the Salt master can be found in the salt\-formula
+for salt itself:
+.sp
+\fI\%https://github.com/saltstack\-formulas/salt\-formula\fP
+.sp
+Restarting the \fBsalt\-master\fP service using execution module or application of
+state could be done the same way as for the Salt minion described \fI\%above\fP\&.
+.SS Is Targeting using Grain Data Secure?
+.sp
+Because grains can be set by users that have access to the minion configuration
+files on the local system, grains are considered less secure than other
+identifiers in Salt. Use caution when targeting sensitive operations or setting
+pillar values based on grain data.
+.sp
+The only grain which can be safely used is \fBgrains[\(aqid\(aq]\fP which contains the Minion ID.
+.sp
+When possible, you should target sensitive operations and data using the Minion
+ID. If the Minion ID of a system changes, the Salt Minion\(aqs public key must be
+re\-accepted by an administrator on the Salt Master, making it less vulnerable
+to impersonation attacks.
+.SS Why Did the Value for a Grain Change on Its Own?
+.sp
+This is usually the result of an upstream change in an OS distribution that
+replaces or removes something that Salt was using to detect the grain.
+Fortunately, when this occurs, you can use Salt to fix it with a command
+similar to the following:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+salt \-G \(aqgrain:ChangedValue\(aq grains.setvals "{\(aqgrain\(aq: \(aqOldValue\(aq}"
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+(Replacing \fIgrain\fP, \fIChangedValue\fP, and \fIOldValue\fP with
+the grain and values that you want to change / set.)
+.sp
+You should also \fI\%file an issue\fP
+describing the change so it can be fixed in Salt.
+.SS Salt Best Practices
+.sp
+Salt\(aqs extreme flexibility leads to many questions concerning the structure of
+configuration files.
+.sp
+This document exists to clarify these points through examples and
+code.
+.SS General rules
+.INDENT 0.0
+.IP 1. 3
+Modularity and clarity should be emphasized whenever possible.
+.IP 2. 3
+Create clear relations between pillars and states.
+.IP 3. 3
+Use variables when it makes sense but don\(aqt overuse them.
+.IP 4. 3
+Store sensitive data in pillar.
+.IP 5. 3
+Don\(aqt use grains for matching in your pillar top file for any sensitive
+pillars.
+.UNINDENT
+.SS Structuring States and Formulas
+.sp
+When structuring Salt States and Formulas it is important to begin with the
+directory structure. A proper directory structure clearly defines the
+functionality of each state to the user via visual inspection of the state\(aqs
+name.
+.sp
+Reviewing the \fI\%MySQL Salt Formula\fP
+it is clear to see the benefits to the end\-user when reviewing a sample of the
+available states:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+/srv/salt/mysql/files/
+/srv/salt/mysql/client.sls
+/srv/salt/mysql/map.jinja
+/srv/salt/mysql/python.sls
+/srv/salt/mysql/server.sls
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+This directory structure would lead to these states being referenced in a top
+file in the following way:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+base:
+ \(aqweb*\(aq:
+ \- mysql.client
+ \- mysql.python
+ \(aqdb*\(aq:
+ \- mysql.server
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+This clear definition ensures that the user is properly informed of what each
+state will do.
+.sp
+Another example comes from the \fI\%vim\-formula\fP:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+/srv/salt/vim/files/
+/srv/salt/vim/absent.sls
+/srv/salt/vim/init.sls
+/srv/salt/vim/map.jinja
+/srv/salt/vim/nerdtree.sls
+/srv/salt/vim/pyflakes.sls
+/srv/salt/vim/salt.sls
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Once again viewing how this would look in a top file:
+.sp
+/srv/salt/top.sls:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+base:
+ \(aqweb*\(aq:
+ \- vim
+ \- vim.nerdtree
+ \- vim.pyflakes
+ \- vim.salt
+ \(aqdb*\(aq:
+ \- vim.absent
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+The usage of a clear top\-level directory as well as properly named states
+reduces the overall complexity and leads a user to both understand what will
+be included at a glance and where it is located.
+.sp
+In addition Formulas should
+be used as often as possible.
+.sp
+\fBNOTE:\fP
+.INDENT 0.0
+.INDENT 3.5
+Formulas repositories on the saltstack\-formulas GitHub organization should
+not be pointed to directly from systems that automatically fetch new
+updates such as GitFS or similar tooling. Instead formulas repositories
+should be forked on GitHub or cloned locally, where unintended, automatic
+changes will not take place.
+.UNINDENT
+.UNINDENT
+.SS Structuring Pillar Files
+.sp
+Pillars are used to store
+secure and insecure data pertaining to minions. When designing the structure
+of the \fB/srv/pillar\fP directory, the pillars contained within
+should once again be focused on clear and concise data which users can easily
+review, modify, and understand.
+.sp
+The \fB/srv/pillar/\fP directory is primarily controlled by \fBtop.sls\fP\&. It
+should be noted that the pillar \fBtop.sls\fP is not used as a location to
+declare variables and their values. The \fBtop.sls\fP is used as a way to
+include other pillar files and organize the way they are matched based on
+environments or grains.
+.sp
+An example \fBtop.sls\fP may be as simple as the following:
+.sp
+/srv/pillar/top.sls:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+base:
+ \(aq*\(aq:
+ \- packages
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Any number of matchers can be added to the base environment. For example, here
+is an expanded version of the Pillar top file stated above:
+.sp
+/srv/pillar/top.sls:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+base:
+ \(aq*\(aq:
+ \- packages
+ \(aqweb*\(aq:
+ \- apache
+ \- vim
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Or an even more complicated example, using a variety of matchers in numerous
+environments:
+.sp
+/srv/pillar/top.sls:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+base:
+ \(aq*\(aq:
+ \- apache
+dev:
+ \(aqos:Debian\(aq:
+ \- match: grain
+ \- vim
+test:
+ \(aq* and not G@os: Debian\(aq:
+ \- match: compound
+ \- emacs
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+It is clear to see through these examples how the top file provides users with
+power but when used incorrectly it can lead to confusing configurations. This
+is why it is important to understand that the top file for pillar is not used
+for variable definitions.
+.sp
+Each SLS file within the \fB/srv/pillar/\fP directory should correspond to the
+states which it matches.
+.sp
+This would mean that the \fBapache\fP pillar file should contain data relevant to
+Apache. Structuring files in this way once again ensures modularity, and
+creates a consistent understanding throughout our Salt environment. Users can
+expect that pillar variables found in an Apache state will live inside of an
+Apache pillar:
+.sp
+\fB/srv/pillar/apache.sls\fP:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+apache:
+ lookup:
+ name: httpd
+ config:
+ tmpl: /etc/httpd/httpd.conf
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+While this pillar file is simple, it shows how a pillar file explicitly
+relates to the state it is associated with.
+.SS Variable Flexibility
+.sp
+Salt allows users to define variables in SLS files. When creating a state
+variables should provide users with as much flexibility as possible. This
+means that variables should be clearly defined and easy to manipulate, and
+that sane defaults should exist in the event a variable is not properly
+defined. Looking at several examples shows how these different items can
+lead to extensive flexibility.
+.sp
+Although it is possible to set variables locally, this is generally not
+preferred:
+.sp
+\fB/srv/salt/apache/conf.sls\fP:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+{% set name = \(aqhttpd\(aq %}
+{% set tmpl = \(aqsalt://apache/files/httpd.conf\(aq %}
+
+include:
+ \- apache
+
+apache_conf:
+ file.managed:
+ \- name: {{ name }}
+ \- source: {{ tmpl }}
+ \- template: jinja
+ \- user: root
+ \- watch_in:
+ \- service: apache
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+When generating this information it can be easily transitioned to the pillar
+where data can be overwritten, modified, and applied to multiple states, or
+locations within a single state:
+.sp
+\fB/srv/pillar/apache.sls\fP:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+apache:
+ lookup:
+ name: httpd
+ config:
+ tmpl: salt://apache/files/httpd.conf
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+\fB/srv/salt/apache/conf.sls\fP:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+{% from "apache/map.jinja" import apache with context %}
+
+include:
+ \- apache
+
+apache_conf:
+ file.managed:
+ \- name: {{ salt[\(aqpillar.get\(aq](\(aqapache:lookup:name\(aq) }}
+ \- source: {{ salt[\(aqpillar.get\(aq](\(aqapache:lookup:config:tmpl\(aq) }}
+ \- template: jinja
+ \- user: root
+ \- watch_in:
+ \- service: apache
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+This flexibility provides users with a centralized location to modify
+variables, which is extremely important as an environment grows.
+.SS Modularity Within States
+.sp
+Ensuring that states are modular is one of the key concepts to understand
+within Salt. When creating a state a user must consider how many times the
+state could be re\-used, and what it relies on to operate. Below are several
+examples which will iteratively explain how a user can go from a state which
+is not very modular to one that is:
+.sp
+\fB/srv/salt/apache/init.sls\fP:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+httpd:
+ pkg:
+ \- installed
+ service.running:
+ \- enable: True
+
+/etc/httpd/httpd.conf:
+ file.managed:
+ \- source: salt://apache/files/httpd.conf
+ \- template: jinja
+ \- watch_in:
+ \- service: httpd
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+The example above is probably the worst\-case scenario when writing a state.
+There is a clear lack of focus by naming both the pkg/service, and managed
+file directly as the state ID. This would lead to changing multiple requires
+within this state, as well as others that may depend upon the state.
+.sp
+Imagine if a require was used for the \fBhttpd\fP package in another state, and
+then suddenly it\(aqs a custom package. Now changes need to be made in multiple
+locations which increases the complexity and leads to a more error prone
+configuration.
+.sp
+There is also the issue of having the configuration file located in the init,
+as a user would be unable to simply install the service and use the default
+conf file.
+.sp
+Our second revision begins to address the referencing by using \fB\- name\fP, as
+opposed to direct ID references:
+.sp
+\fB/srv/salt/apache/init.sls\fP:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+apache:
+ pkg.installed:
+ \- name: httpd
+ service.running:
+ \- name: httpd
+ \- enable: True
+
+apache_conf:
+ file.managed:
+ \- name: /etc/httpd/httpd.conf
+ \- source: salt://apache/files/httpd.conf
+ \- template: jinja
+ \- watch_in:
+ \- service: apache
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+The above init file is better than our original, yet it has several issues
+which lead to a lack of modularity. The first of these problems is the usage
+of static values for items such as the name of the service, the name of the
+managed file, and the source of the managed file. When these items are hard
+coded they become difficult to modify and the opportunity to make mistakes
+arises. It also leads to multiple edits that need to occur when changing
+these items (imagine if there were dozens of these occurrences throughout the
+state!). There is also still the concern of the configuration file data living
+in the same state as the service and package.
+.sp
+In the next example steps will be taken to begin addressing these issues.
+Starting with the addition of a map.jinja file (as noted in the
+Formula documentation), and
+modification of static values:
+.sp
+\fB/srv/salt/apache/map.jinja\fP:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+{% set apache = salt[\(aqgrains.filter_by\(aq]({
+ \(aqDebian\(aq: {
+ \(aqserver\(aq: \(aqapache2\(aq,
+ \(aqservice\(aq: \(aqapache2\(aq,
+ \(aqconf\(aq: \(aq/etc/apache2/apache.conf\(aq,
+ },
+ \(aqRedHat\(aq: {
+ \(aqserver\(aq: \(aqhttpd\(aq,
+ \(aqservice\(aq: \(aqhttpd\(aq,
+ \(aqconf\(aq: \(aq/etc/httpd/httpd.conf\(aq,
+ },
+}, merge=salt[\(aqpillar.get\(aq](\(aqapache:lookup\(aq)) %}
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+/srv/pillar/apache.sls:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+apache:
+ lookup:
+ config:
+ tmpl: salt://apache/files/httpd.conf
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+\fB/srv/salt/apache/init.sls\fP:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+{% from "apache/map.jinja" import apache with context %}
+
+apache:
+ pkg.installed:
+ \- name: {{ apache.server }}
+ service.running:
+ \- name: {{ apache.service }}
+ \- enable: True
+
+apache_conf:
+ file.managed:
+ \- name: {{ apache.conf }}
+ \- source: {{ salt[\(aqpillar.get\(aq](\(aqapache:lookup:config:tmpl\(aq) }}
+ \- template: jinja
+ \- user: root
+ \- watch_in:
+ \- service: apache
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+The changes to this state now allow us to easily identify the location of the
+variables, as well as ensuring they are flexible and easy to modify.
+While this takes another step in the right direction, it is not yet complete.
+Suppose the user did not want to use the provided conf file, or even their own
+configuration file, but the default apache conf. With the current state setup
+this is not possible. To attain this level of modularity this state will need
+to be broken into two states.
+.sp
+\fB/srv/salt/apache/map.jinja\fP:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+{% set apache = salt[\(aqgrains.filter_by\(aq]({
+ \(aqDebian\(aq: {
+ \(aqserver\(aq: \(aqapache2\(aq,
+ \(aqservice\(aq: \(aqapache2\(aq,
+ \(aqconf\(aq: \(aq/etc/apache2/apache.conf\(aq,
+ },
+ \(aqRedHat\(aq: {
+ \(aqserver\(aq: \(aqhttpd\(aq,
+ \(aqservice\(aq: \(aqhttpd\(aq,
+ \(aqconf\(aq: \(aq/etc/httpd/httpd.conf\(aq,
+ },
+}, merge=salt[\(aqpillar.get\(aq](\(aqapache:lookup\(aq)) %}
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+\fB/srv/pillar/apache.sls\fP:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+apache:
+ lookup:
+ config:
+ tmpl: salt://apache/files/httpd.conf
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+\fB/srv/salt/apache/init.sls\fP:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+{% from "apache/map.jinja" import apache with context %}
+
+apache:
+ pkg.installed:
+ \- name: {{ apache.server }}
+ service.running:
+ \- name: {{ apache.service }}
+ \- enable: True
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+\fB/srv/salt/apache/conf.sls\fP:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+{% from "apache/map.jinja" import apache with context %}
+
+include:
+ \- apache
+
+apache_conf:
+ file.managed:
+ \- name: {{ apache.conf }}
+ \- source: {{ salt[\(aqpillar.get\(aq](\(aqapache:lookup:config:tmpl\(aq) }}
+ \- template: jinja
+ \- user: root
+ \- watch_in:
+ \- service: apache
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+This new structure now allows users to choose whether they only wish to
+install the default Apache, or if they wish, overwrite the default package,
+service, configuration file location, or the configuration file itself. In
+addition to this the data has been broken between multiple files allowing for
+users to identify where they need to change the associated data.
+.SS Storing Secure Data
+.sp
+Secure data refers to any information that you would not wish to share with
+anyone accessing a server. This could include data such as passwords,
+keys, or other information.
+.sp
+As all data within a state is accessible by EVERY server that is connected
+it is important to store secure data within pillar. This will ensure that only
+those servers which require this secure data have access to it. In this
+example a use can go from an insecure configuration to one which is only
+accessible by the appropriate hosts:
+.sp
+\fB/srv/salt/mysql/testerdb.sls\fP:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+testdb:
+ mysql_database.present:
+ \- name: testerdb
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+\fB/srv/salt/mysql/user.sls\fP:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+include:
+ \- mysql.testerdb
+
+testdb_user:
+ mysql_user.present:
+ \- name: frank
+ \- password: "test3rdb"
+ \- host: localhost
+ \- require:
+ \- sls: mysql.testerdb
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Many users would review this state and see that the password is there in plain
+text, which is quite problematic. It results in several issues which may not
+be immediately visible.
+.sp
+The first of these issues is clear to most users \-\- the password being visible
+in this state. This means that any minion will have a copy of this, and
+therefore the password which is a major security concern as minions may not
+be locked down as tightly as the master server.
+.sp
+The other issue that can be encountered is access by users on the master. If
+everyone has access to the states (or their repository), then they are able to
+review this password. Keeping your password data accessible by only a few
+users is critical for both security and peace of mind.
+.sp
+There is also the issue of portability. When a state is configured this way
+it results in multiple changes needing to be made. This was discussed in the
+sections above but it is a critical idea to drive home. If states are not
+portable it may result in more work later!
+.sp
+Fixing this issue is relatively simple, the content just needs to be moved to
+the associated pillar:
+.sp
+\fB/srv/pillar/mysql.sls\fP:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+mysql:
+ lookup:
+ name: testerdb
+ password: test3rdb
+ user: frank
+ host: localhost
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+\fB/srv/salt/mysql/testerdb.sls\fP:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+testdb:
+ mysql_database.present:
+ \- name: {{ salt[\(aqpillar.get\(aq](\(aqmysql:lookup:name\(aq) }}
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+\fB/srv/salt/mysql/user.sls\fP:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+include:
+ \- mysql.testerdb
+
+testdb_user:
+ mysql_user.present:
+ \- name: {{ salt[\(aqpillar.get\(aq](\(aqmysql:lookup:user\(aq) }}
+ \- password: {{ salt[\(aqpillar.get\(aq](\(aqmysql:lookup:password\(aq) }}
+ \- host: {{ salt[\(aqpillar.get\(aq](\(aqmysql:lookup:host\(aq) }}
+ \- require:
+ \- sls: mysql.testerdb
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Now that the database details have been moved to the associated pillar file,
+only machines which are targeted via pillar will have access to these details.
+Access to users who should not be able to review these details can also be
+prevented while ensuring that they are still able to write states which take
+advantage of this information.
+.SH REMOTE EXECUTION
+.sp
+Running pre\-defined or arbitrary commands on remote hosts, also known as
+remote execution, is the core function of Salt. The following links explore
+modules and returners, which are two key elements of remote execution.
+.sp
+\fBSalt Execution Modules\fP
+.sp
+Salt execution modules are called by the remote execution system to perform
+a wide variety of tasks. These modules provide functionality such as installing
+packages, restarting a service, running a remote command, transferring files,
+and so on.
+.INDENT 0.0
+.INDENT 3.5
+.INDENT 0.0
+.TP
+.B Full list of execution modules
+Contains: a list of core modules that ship with Salt.
+.TP
+.B Writing execution modules
+Contains: a guide on how to write Salt modules.
+.UNINDENT
+.UNINDENT
+.UNINDENT
+.SS Running Commands on Salt Minions
+.sp
+Salt can be controlled by a command line client by the root user on the Salt
+master. The Salt command line client uses the Salt client API to communicate
+with the Salt master server. The Salt client is straightforward and simple
+to use.
+.sp
+Using the Salt client commands can be easily sent to the minions.
+.sp
+Each of these commands accepts an explicit \fI\-\-config\fP option to point to either
+the master or minion configuration file. If this option is not provided and
+the default configuration file does not exist then Salt falls back to use the
+environment variables \fBSALT_MASTER_CONFIG\fP and \fBSALT_MINION_CONFIG\fP\&.
+.sp
+\fBSEE ALSO:\fP
+.INDENT 0.0
+.INDENT 3.5
+Configuration
+.UNINDENT
+.UNINDENT
+.SS Using the Salt Command
+.sp
+The Salt command needs a few components to send information to the Salt
+minions. The target minions need to be defined, the function to call and any
+arguments the function requires.
+.SS Defining the Target Minions
+.sp
+The first argument passed to salt, defines the target minions, the target
+minions are accessed via their hostname. The default target type is a bash
+glob:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+salt \(aq*foo.com\(aq sys.doc
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Salt can also define the target minions with regular expressions:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+salt \-E \(aq.*\(aq cmd.run \(aqls \-l | grep foo\(aq
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Or to explicitly list hosts, salt can take a list:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+salt \-L foo.bar.baz,quo.qux cmd.run \(aqps aux | grep foo\(aq
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.SS More Powerful Targets
+.sp
+See Targeting\&.
+.SS Calling the Function
+.sp
+The function to call on the specified target is placed after the target
+specification.
+.sp
+New in version 0.9.8.
+
+.sp
+Functions may also accept arguments, space\-delimited:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+salt \(aq*\(aq cmd.exec_code python \(aqimport sys; print sys.version\(aq
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Optional, keyword arguments are also supported:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+salt \(aq*\(aq pip.install salt timeout=5 upgrade=True
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+They are always in the form of \fBkwarg=argument\fP\&.
+.sp
+Arguments are formatted as YAML:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+salt \(aq*\(aq cmd.run \(aqecho "Hello: $FIRST_NAME"\(aq saltenv=\(aq{FIRST_NAME: "Joe"}\(aq
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Note: dictionaries must have curly braces around them (like the \fBsaltenv\fP
+keyword argument above). This was changed in 0.15.1: in the above example,
+the first argument used to be parsed as the dictionary
+\fB{\(aqecho "Hello\(aq: \(aq$FIRST_NAME"\(aq}\fP\&. This was generally not the expected
+behavior.
+.sp
+If you want to test what parameters are actually passed to a module, use the
+\fBtest.arg_repr\fP command:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+salt \(aq*\(aq test.arg_repr \(aqecho "Hello: $FIRST_NAME"\(aq saltenv=\(aq{FIRST_NAME: "Joe"}\(aq
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.SS Finding available minion functions
+.sp
+The Salt functions are self documenting, all of the function documentation can
+be retried from the minions via the \fBsys.doc()\fP function:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+salt \(aq*\(aq sys.doc
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.SS Compound Command Execution
+.sp
+If a series of commands needs to be sent to a single target specification then
+the commands can be sent in a single publish. This can make gathering
+groups of information faster, and lowers the stress on the network for repeated
+commands.
+.sp
+Compound command execution works by sending a list of functions and arguments
+instead of sending a single function and argument. The functions are executed
+on the minion in the order they are defined on the command line, and then the
+data from all of the commands are returned in a dictionary. This means that
+the set of commands are called in a predictable way, and the returned data can
+be easily interpreted.
+.sp
+Executing compound commands if done by passing a comma delimited list of
+functions, followed by a comma delimited list of arguments:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+salt \(aq*\(aq cmd.run,test.ping,test.echo \(aqcat /proc/cpuinfo\(aq,,foo
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+The trick to look out for here, is that if a function is being passed no
+arguments, then there needs to be a placeholder for the absent arguments. This
+is why in the above example, there are two commas right next to each other.
+\fBtest.ping\fP takes no arguments, so we need to add another comma, otherwise
+Salt would attempt to pass "foo" to \fBtest.ping\fP\&.
+.sp
+If you need to pass arguments that include commas, then make sure you add
+spaces around the commas that separate arguments. For example:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+salt \(aq*\(aq cmd.run,test.ping,test.echo \(aqecho "1,2,3"\(aq , , foo
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+You may change the arguments separator using the \fB\-\-args\-separator\fP option:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+salt \-\-args\-separator=:: \(aq*\(aq some.fun,test.echo params with , comma :: foo
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.SS CLI Completion
+.sp
+Shell completion scripts for the Salt CLI are available in the \fBpkg\fP Salt
+\fI\%source directory\fP\&.
+.SS Writing Execution Modules
+.sp
+Salt execution modules are the functions called by the \fBsalt\fP command.
+.SS Modules Are Easy to Write!
+.sp
+Writing Salt execution modules is straightforward.
+.sp
+A Salt execution module is a Python or \fI\%Cython\fP module placed in a directory
+called \fB_modules/\fP at the root of the Salt fileserver. When using the default
+fileserver backend (i.e. \fBroots .pyx\fP so that
+the loader knows that the module needs to be imported as a Cython module. The
+compilation of the Cython module is automatic and happens when the minion
+starts, so only the \fB*.pyx\fP file is required.
+.SS Zip Archives as Modules
+.sp
+Python 2.3 and higher allows developers to directly import zip archives
+containing Python code. By setting \fBenable_zip_modules\fP to
+\fBTrue\fP in the minion config, the Salt loader will be able to import \fB\&.zip\fP
+files in this fashion. This allows Salt module developers to package
+dependencies with their modules for ease of deployment, isolation, etc.
+.sp
+For a user, Zip Archive modules behave just like other modules. When executing
+a function from a module provided as the file \fBmy_module.zip\fP, a user would
+call a function within that module as \fBmy_module.\fP\&.
+.SS Creating a Zip Archive Module
+.sp
+A Zip Archive module is structured similarly to a simple \fI\%Python package\fP\&.
+The \fB\&.zip\fP file contains a single directory with the same name as the module.
+The module code traditionally in \fB.py\fP goes in
+\fB/__init__.py\fP\&. The dependency packages are subdirectories of
+\fB/\fP\&.
+.sp
+Here is an example directory structure for the \fBlumberjack\fP module, which has
+two library dependencies (\fBsleep\fP and \fBwork\fP) to be included.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+modules $ ls \-R lumberjack
+__init__.py sleep work
+
+lumberjack/sleep:
+__init__.py
+
+lumberjack/work:
+__init__.py
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+The contents of \fBlumberjack/__init__.py\fP show how to import and use these
+included libraries.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+# Libraries included in lumberjack.zip
+from lumberjack import sleep, work
+
+
+def is_ok(person):
+ \(aq\(aq\(aq Checks whether a person is really a lumberjack \(aq\(aq\(aq
+ return sleep.all_night(person) and work.all_day(person)
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Then, create the zip:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+modules $ zip \-r lumberjack lumberjack
+ adding: lumberjack/ (stored 0%)
+ adding: lumberjack/__init__.py (deflated 39%)
+ adding: lumberjack/sleep/ (stored 0%)
+ adding: lumberjack/sleep/__init__.py (deflated 7%)
+ adding: lumberjack/work/ (stored 0%)
+ adding: lumberjack/work/__init__.py (deflated 7%)
+modules $ unzip \-l lumberjack.zip
+Archive: lumberjack.zip
+ Length Date Time Name
+ \-\-\-\-\-\-\-\- \-\-\-\- \-\-\-\- \-\-\-\-
+ 0 08\-21\-15 20:08 lumberjack/
+ 348 08\-21\-15 20:08 lumberjack/__init__.py
+ 0 08\-21\-15 19:53 lumberjack/sleep/
+ 83 08\-21\-15 19:53 lumberjack/sleep/__init__.py
+ 0 08\-21\-15 19:53 lumberjack/work/
+ 81 08\-21\-15 19:21 lumberjack/work/__init__.py
+ \-\-\-\-\-\-\-\- \-\-\-\-\-\-\-
+ 512 6 files
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Once placed in \fBfile_roots\fP, Salt users can distribute and use
+\fBlumberjack.zip\fP like any other module.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+$ sudo salt minion1 saltutil.sync_modules
+minion1:
+ \- modules.lumberjack
+$ sudo salt minion1 lumberjack.is_ok \(aqMichael Palin\(aq
+minion1:
+ True
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.SS Cross Calling Execution Modules
+.sp
+All of the Salt execution modules are available to each other and modules can
+call functions available in other execution modules.
+.sp
+The variable \fB__salt__\fP is packed into the modules after they are loaded into
+the Salt minion.
+.sp
+The \fB__salt__\fP variable is a \fI\%Python dictionary\fP
+containing all of the Salt functions. Dictionary keys are strings representing
+the names of the modules and the values are the functions themselves.
+.sp
+Salt modules can be cross\-called by accessing the value in the \fB__salt__\fP
+dict:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+def foo(bar):
+ return __salt__[\(aqcmd.run\(aq](bar)
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+This code will call the \fIrun\fP function in the \fBcmd\fP
+module and pass the argument \fBbar\fP to it.
+.SS Calling Execution Modules on the Salt Master
+.sp
+New in version 2016.11.0.
+
+.sp
+Execution modules can now also be called via the \fBsalt\-run\fP command
+using the salt runner\&.
+.SS Preloaded Execution Module Data
+.sp
+When interacting with execution modules often it is nice to be able to read
+information dynamically about the minion or to load in configuration parameters
+for a module.
+.sp
+Salt allows for different types of data to be loaded into the modules by the
+minion.
+.SS Grains Data
+.sp
+The values detected by the Salt Grains on the minion are available in a
+\fI\%Python dictionary\fP named \fB__grains__\fP and can be
+accessed from within callable objects in the Python modules.
+.sp
+To see the contents of the grains dictionary for a given system in your
+deployment run the \fBgrains.items()\fP function:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+salt \(aqhostname\(aq grains.items \-\-output=pprint
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Any value in a grains dictionary can be accessed as any other Python
+dictionary. For example, the grain representing the minion ID is stored in the
+\fBid\fP key and from an execution module, the value would be stored in
+\fB__grains__[\(aqid\(aq]\fP\&.
+.SS Module Configuration
+.sp
+Since parameters for configuring a module may be desired, Salt allows for
+configuration information from the minion configuration file to be passed to
+execution modules.
+.sp
+Since the minion configuration file is a YAML document, arbitrary configuration
+data can be passed in the minion config that is read by the modules. It is
+therefore \fBstrongly\fP recommended that the values passed in the configuration
+file match the module name. A value intended for the \fBtest\fP execution module
+should be named \fBtest.\fP\&.
+.sp
+The test execution module contains usage of the module configuration and the
+default configuration file for the minion contains the information and format
+used to pass data to the modules. \fBsalt.modules.test\fP,
+\fBconf/minion\fP\&.
+.SS Strings and Unicode
+.sp
+An execution module author should always assume that strings fed to the module
+have already decoded from strings into Unicode. In Python 2, these will
+be of type \(aqUnicode\(aq and in Python 3 they will be of type \fBstr\fP\&. Calling
+from a state to other Salt sub\-systems, should pass Unicode (or bytes if passing binary data). In the
+rare event that a state needs to write directly to disk, Unicode should be
+encoded to a string immediately before writing to disk. An author may use
+\fB__salt_system_encoding__\fP to learn what the encoding type of the system is.
+For example, \fI\(aqmy_string\(aq.encode(__salt_system_encoding__\(aq)\fP\&.
+.SS Outputter Configuration
+.sp
+Since execution module functions can return different data, and the way the
+data is printed can greatly change the presentation, Salt allows for a specific
+outputter to be set on a function\-by\-function basis.
+.sp
+This is done be declaring an \fB__outputter__\fP dictionary in the global scope
+of the module. The \fB__outputter__\fP dictionary contains a mapping of function
+names to Salt outputters\&.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+__outputter__ = {
+ \(aqrun\(aq: \(aqtxt\(aq
+}
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+This will ensure that the \fBtxt\fP outputter is used to display output from the
+\fBrun\fP function.
+.SS Virtual Modules
+.sp
+Virtual modules let you override the name of a module in order to use the same
+name to refer to one of several similar modules. The specific module that is
+loaded for a virtual name is selected based on the current platform or
+environment.
+.sp
+For example, packages are managed across platforms using the \fBpkg\fP module.
+\fBpkg\fP is a virtual module name that is an alias for the specific package
+manager module that is loaded on a specific system (for example, \fByumpkg\fP on RHEL/CentOS systems , and \fBaptpkg\fP on Ubuntu).
+.sp
+Virtual module names are set using the \fB__virtual__\fP function and the
+\fI\%virtual name\fP\&.
+.SS \fB__virtual__\fP Function
+.sp
+The \fB__virtual__\fP function returns either a \fI\%string\fP,
+\fI\%True\fP, \fI\%False\fP, or \fI\%False\fP with an \fI\%error
+string\fP\&. If a string is returned then the module is loaded
+using the name of the string as the virtual name. If \fBTrue\fP is returned the
+module is loaded using the current module name. If \fBFalse\fP is returned the
+module is not loaded. \fBFalse\fP lets the module perform system checks and
+prevent loading if dependencies are not met.
+.sp
+Since \fB__virtual__\fP is called before the module is loaded, \fB__salt__\fP will
+be unavailable as it will not have been packed into the module at this point in
+time.
+.sp
+\fBNOTE:\fP
+.INDENT 0.0
+.INDENT 3.5
+Modules which return a string from \fB__virtual__\fP that is already used by
+a module that ships with Salt will _override_ the stock module.
+.UNINDENT
+.UNINDENT
+.SS Returning Error Information from \fB__virtual__\fP
+.sp
+Optionally, Salt plugin modules, such as execution, state, returner, beacon,
+etc. modules may additionally return a string containing the reason that a
+module could not be loaded. For example, an execution module called \fBcheese\fP
+and a corresponding state module also called \fBcheese\fP, both depending on a
+utility called \fBenzymes\fP should have \fB__virtual__\fP functions that handle
+the case when the dependency is unavailable.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+\(aq\(aq\(aq
+Cheese execution (or returner/beacon/etc.) module
+\(aq\(aq\(aq
+try:
+ import enzymes
+ HAS_ENZYMES = True
+except ImportError:
+ HAS_ENZYMES = False
+
+
+def __virtual__():
+ \(aq\(aq\(aq
+ only load cheese if enzymes are available
+ \(aq\(aq\(aq
+ if HAS_ENZYMES:
+ return \(aqcheese\(aq
+ else:
+ return False, \(aqThe cheese execution module cannot be loaded: enzymes unavailable.\(aq
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+\(aq\(aq\(aq
+Cheese state module
+\(aq\(aq\(aq
+
+def __virtual__():
+ \(aq\(aq\(aq
+ only load cheese if enzymes are available
+ \(aq\(aq\(aq
+ # predicate loading of the cheese state on the corresponding execution module
+ if \(aqcheese.slice\(aq in __salt__:
+ return \(aqcheese\(aq
+ else:
+ return False, \(aqThe cheese state module cannot be loaded: enzymes unavailable.\(aq
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.SS Examples
+.sp
+The package manager modules are among the best examples of using the
+\fB__virtual__\fP function. A table of all the virtual \fBpkg\fP modules can be
+found here\&.
+.SS Overriding Virtual Module Providers
+.sp
+Salt often uses OS grains (\fBos\fP, \fBosrelease\fP, \fBos_family\fP, etc.) to
+determine which module should be loaded as the virtual module for \fBpkg\fP,
+\fBservice\fP, etc. Sometimes this OS detection is incomplete, with new distros
+popping up, existing distros changing init systems, etc. The virtual modules
+likely to be affected by this are in the list below (click each item for more
+information):
+.INDENT 0.0
+.IP \(bu 2
+pkg
+.IP \(bu 2
+service
+.IP \(bu 2
+user
+.IP \(bu 2
+shadow
+.IP \(bu 2
+group
+.UNINDENT
+.sp
+If Salt is using the wrong module for one of these, first of all, please
+\fI\%report it on the issue tracker\fP, so that this issue can be resolved for a
+future release. To make it easier to troubleshoot, please also provide the
+\fBgrains.items\fP output, taking care to
+redact any sensitive information.
+.sp
+Then, while waiting for the SaltStack development team to fix the issue, Salt
+can be made to use the correct module using the \fBproviders\fP option
+in the minion config file:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+providers:
+ service: systemd
+ pkg: aptpkg
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+The above example will force the minion to use the \fBsystemd\fP module to provide service management, and the
+\fBaptpkg\fP module to provide package management.
+.SS Logging Restrictions
+.sp
+As a rule, logging should not be done anywhere in a Salt module before it is
+loaded. This rule apples to all code that would run before the \fB__virtual__()\fP
+function, as well as the code within the \fB__virtual__()\fP function itself.
+.sp
+If logging statements are made before the virtual function determines if
+the module should be loaded, then those logging statements will be called
+repeatedly. This clutters up log files unnecessarily.
+.sp
+Exceptions may be considered for logging statements made at the \fBtrace\fP level.
+However, it is better to provide the necessary information by another means.
+One method is to \fI\%return error information\fP in the
+\fB__virtual__()\fP function.
+.SS \fB__virtualname__\fP
+.sp
+\fB__virtualname__\fP is a variable that is used by the documentation build
+system to know the virtual name of a module without calling the \fB__virtual__\fP
+function. Modules that return a string from the \fB__virtual__\fP function
+must also set the \fB__virtualname__\fP variable.
+.sp
+To avoid setting the virtual name string twice, you can implement
+\fB__virtual__\fP to return the value set for \fB__virtualname__\fP using a pattern
+similar to the following:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+# Define the module\(aqs virtual name
+__virtualname__ = \(aqpkg\(aq
+
+
+def __virtual__():
+ \(aq\(aq\(aq
+ Confine this module to Mac OS with Homebrew.
+ \(aq\(aq\(aq
+
+ if salt.utils.which(\(aqbrew\(aq) and __grains__[\(aqos\(aq] == \(aqMacOS\(aq:
+ return __virtualname__
+ return False
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+The \fB__virtual__()\fP function can return a \fBTrue\fP or \fBFalse\fP boolean, a tuple,
+or a string. If it returns a \fBTrue\fP value, this \fB__virtualname__\fP module\-level
+attribute can be set as seen in the above example. This is the string that the module
+should be referred to as.
+.sp
+When \fB__virtual__()\fP returns a tuple, the first item should be a boolean and the
+second should be a string. This is typically done when the module should not load. The
+first value of the tuple is \fBFalse\fP and the second is the error message to display
+for why the module did not load.
+.sp
+For example:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+def __virtual__():
+ \(aq\(aq\(aq
+ Only load if git exists on the system
+ \(aq\(aq\(aq
+ if salt.utils.which(\(aqgit\(aq) is None:
+ return (False,
+ \(aqThe git execution module cannot be loaded: git unavailable.\(aq)
+ else:
+ return True
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.SS Documentation
+.sp
+Salt execution modules are documented. The \fBsys.doc()\fP function will return
+the documentation for all available modules:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+salt \(aq*\(aq sys.doc
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+The \fBsys.doc\fP function simply prints out the docstrings found in the modules;
+when writing Salt execution modules, please follow the formatting conventions
+for docstrings as they appear in the other modules.
+.SS Adding Documentation to Salt Modules
+.sp
+It is strongly suggested that all Salt modules have documentation added.
+.sp
+To add documentation add a \fI\%Python docstring\fP to the function.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+def spam(eggs):
+ \(aq\(aq\(aq
+ A function to make some spam with eggs!
+
+ CLI Example::
+
+ salt \(aq*\(aq test.spam eggs
+ \(aq\(aq\(aq
+ return eggs
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Now when the sys.doc call is executed the docstring will be cleanly returned
+to the calling terminal.
+.sp
+Documentation added to execution modules in docstrings will automatically be
+added to the online web\-based documentation.
+.SS Add Execution Module Metadata
+.sp
+When writing a Python docstring for an execution module, add information about
+the module using the following field lists:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+:maintainer: Thomas Hatch
+:maturity: new
+:depends: python\-mysqldb
+:platform: all
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+The maintainer field is a comma\-delimited list of developers who help maintain
+this module.
+.sp
+The maturity field indicates the level of quality and testing for this module.
+Standard labels will be determined.
+.sp
+The depends field is a comma\-delimited list of modules that this module depends
+on.
+.sp
+The platform field is a comma\-delimited list of platforms that this module is
+known to run on.
+.SS Log Output
+.sp
+You can call the logger from custom modules to write messages to the minion
+logs. The following code snippet demonstrates writing log messages:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+import logging
+
+log = logging.getLogger(__name__)
+
+log.info(\(aqHere is Some Information\(aq)
+log.warning(\(aqYou Should Not Do That\(aq)
+log.error(\(aqIt Is Busted\(aq)
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.SS Aliasing Functions
+.sp
+Sometimes one wishes to use a function name that would shadow a python built\-in.
+A common example would be \fBset()\fP\&. To support this, append an underscore to
+the function definition, \fBdef set_():\fP, and use the \fB__func_alias__\fP feature
+to provide an alias to the function.
+.sp
+\fB__func_alias__\fP is a dictionary where each key is the name of a function in
+the module, and each value is a string representing the alias for that function.
+When calling an aliased function from a different execution module, state
+module, or from the cli, the alias name should be used.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+__func_alias__ = {
+ \(aqset_\(aq: \(aqset\(aq,
+ \(aqlist_\(aq: \(aqlist\(aq,
+}
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.SS Private Functions
+.sp
+In Salt, Python callable objects contained within an execution module are made
+available to the Salt minion for use. The only exception to this rule is a
+callable object with a name starting with an underscore \fB_\fP\&.
+.SS Objects Loaded Into the Salt Minion
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+def foo(bar):
+ return bar
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.SS Objects NOT Loaded into the Salt Minion
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+def _foobar(baz): # Preceded with an _
+ return baz
+
+cheese = {} # Not a callable Python object
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.SS Useful Decorators for Modules
+.SS Depends Decorator
+.sp
+When writing execution modules there are many times where some of the module
+will work on all hosts but some functions have an external dependency, such as
+a service that needs to be installed or a binary that needs to be present on
+the system.
+.sp
+Instead of trying to wrap much of the code in large try/except blocks, a
+decorator can be used.
+.sp
+If the dependencies passed to the decorator don\(aqt exist, then the salt minion
+will remove those functions from the module on that host.
+.sp
+If a \fBfallback_function\fP is defined, it will replace the function instead of
+removing it
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+import logging
+
+from salt.utils.decorators import depends
+
+log = logging.getLogger(__name__)
+
+try:
+ import dependency_that_sometimes_exists
+except ImportError as e:
+ log.trace(\(aqFailed to import dependency_that_sometimes_exists: {0}\(aq.format(e))
+
+@depends(\(aqdependency_that_sometimes_exists\(aq)
+def foo():
+ \(aq\(aq\(aq
+ Function with a dependency on the "dependency_that_sometimes_exists" module,
+ if the "dependency_that_sometimes_exists" is missing this function will not exist
+ \(aq\(aq\(aq
+ return True
+
+def _fallback():
+ \(aq\(aq\(aq
+ Fallback function for the depends decorator to replace a function with
+ \(aq\(aq\(aq
+ return \(aq"dependency_that_sometimes_exists" needs to be installed for this function to exist\(aq
+
+@depends(\(aqdependency_that_sometimes_exists\(aq, fallback_function=_fallback)
+def foo():
+ \(aq\(aq\(aq
+ Function with a dependency on the "dependency_that_sometimes_exists" module.
+ If the "dependency_that_sometimes_exists" is missing this function will be
+ replaced with "_fallback"
+ \(aq\(aq\(aq
+ return True
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+In addition to global dependencies the depends decorator also supports raw
+booleans.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+from salt.utils.decorators import depends
+
+HAS_DEP = False
+try:
+ import dependency_that_sometimes_exists
+ HAS_DEP = True
+except ImportError:
+ pass
+
+@depends(HAS_DEP)
+def foo():
+ return True
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.SH CONFIGURATION MANAGEMENT
+.sp
+Salt contains a robust and flexible configuration management framework, which
+is built on the remote execution core. This framework executes on the minions,
+allowing effortless, simultaneous configuration of tens of thousands of hosts,
+by rendering language specific state files. The following links provide
+resources to learn more about state and renderers.
+.INDENT 0.0
+.TP
+.B \fBStates\fP
+Express the state of a host using small, easy to read, easy to
+understand configuration files. \fINo programming required\fP\&.
+.INDENT 7.0
+.TP
+.B Full list of states
+Contains: list of install packages, create users, transfer files, start
+services, and so on.
+.TP
+.B Pillar System
+Contains: description of Salt\(aqs Pillar system.
+.TP
+.B Highstate data structure
+Contains: a dry vocabulary and technical representation of the
+configuration format that states represent.
+.TP
+.B Writing states
+Contains: a guide on how to write Salt state modules, easily extending
+Salt to directly manage more software.
+.UNINDENT
+.UNINDENT
+.sp
+\fBNOTE:\fP
+.INDENT 0.0
+.INDENT 3.5
+Salt execution modules are different from state modules and cannot be
+called as a state in an SLS file. In other words, this will not work:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+moe:
+ user.rename:
+ \- new_name: larry
+ \- onlyif: id moe
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+You must use the \fBmodule\fP states to call
+execution modules directly. Here\(aqs an example:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+rename_moe:
+ module.run:
+ \- m_name: moe
+ \- new_name: larry
+ \- onlyif: id moe
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.UNINDENT
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \fBRenderers\fP
+Renderers use state configuration files written in a variety of languages,
+templating engines, or files. Salt\(aqs configuration management system is,
+under the hood, language agnostic.
+.INDENT 7.0
+.TP
+.B Full list of renderers
+Contains: a list of renderers.
+YAML is one choice, but many systems are available, from
+alternative templating engines to the PyDSL language for rendering
+sls formulas.
+.TP
+.B Renderers
+Contains: more information about renderers. Salt states are only
+concerned with the ultimate highstate data structure, not how the
+data structure was created.
+.UNINDENT
+.UNINDENT
.SS State System Reference
.sp
Salt offers an interface to manage the configuration or "state" of the
@@ -44150,6 +51544,28 @@ actually speed things up.
.sp
To run the above state much faster make sure that the \fBsleep 5\fP is evaluated
before the \fBnginx\fP state
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+sleep 10:
+ cmd.run:
+ \- parallel: True
+
+sleep 5:
+ cmd.run:
+ \- parallel: True
+
+nginx:
+ service.running:
+ \- parallel: True
+ \- require:
+ \- cmd: sleep 10
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
.sp
Now both of the sleep calls will be started in parallel and \fBnginx\fP will still
wait for the state it requires, but while it waits the \fBsleep 5\fP state will
@@ -44253,7 +51669,7 @@ the targeting state. The following example demonstrates a direct requisite:
.nf
.ft C
vim:
- pkg.installed: []
+ pkg.installed
/etc/vimrc:
file.managed:
@@ -44883,7 +52299,7 @@ id declaration. This is useful when many files need to have the same defaults.
\- group: apache
\- mode: 755
-/etc/bar.conf
+/etc/bar.conf:
file.managed:
\- source: salt://bar.conf
\- use:
@@ -45289,10 +52705,10 @@ same privileges as the salt\-minion.
comment\-repo:
file.replace:
\- name: /etc/yum.repos.d/fedora.repo
- \- pattern: ^enabled=0
+ \- pattern: \(aq^enabled=0\(aq
\- repl: enabled=1
\- check_cmd:
- \- ! grep \(aqenabled=0\(aq /etc/yum.repos.d/fedora.repo
+ \- "! grep \(aqenabled=0\(aq /etc/yum.repos.d/fedora.repo"
.ft P
.fi
.UNINDENT
@@ -46338,7 +53754,7 @@ illustrate:
.sp
.nf
.ft C
-/etc/salt/master: # maps to "name"
+/etc/salt/master: # maps to "name", unless a "name" argument is specified below
file.managed: # maps to . \- e.g. "managed" in https://github.com/saltstack/salt/tree/develop/salt/states/file.py
\- user: root # one of many options passed to the manage function
\- group: root
@@ -46370,19 +53786,154 @@ An example of how these keyword arguments can be handled can be found
\fI\%here\fP\&.
.UNINDENT
.UNINDENT
+.SS Best Practices
+.sp
+A well\-written state function will follow these steps:
+.sp
+\fBNOTE:\fP
+.INDENT 0.0
+.INDENT 3.5
+This is an extremely simplified example. Feel free to browse the \fI\%source
+code\fP for Salt\(aqs state modules to see other examples.
+.UNINDENT
+.UNINDENT
+.INDENT 0.0
+.IP 1. 3
+Set up the return dictionary and perform any necessary input validation
+(type checking, looking for use of mutually\-exclusive arguments, etc.).
+.INDENT 3.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+ret = {\(aqname\(aq: name,
+ \(aqresult\(aq: False,
+ \(aqchanges\(aq: {},
+ \(aqcomment\(aq: \(aq\(aq}
+
+if foo and bar:
+ ret[\(aqcomment\(aq] = \(aqOnly one of foo and bar is permitted\(aq
+ return ret
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.IP 2. 3
+Check if changes need to be made. This is best done with an
+information\-gathering function in an accompanying execution module\&. The state should be able to use the return
+from this function to tell whether or not the minion is already in the
+desired state.
+.INDENT 3.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+result = __salt__[\(aqmodname.check\(aq](name)
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.IP 3. 3
+If step 2 found that the minion is already in the desired state, then exit
+immediately with a \fBTrue\fP result and without making any changes.
+.INDENT 3.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+if result:
+ ret[\(aqresult\(aq] = True
+ ret[\(aqcomment\(aq] = \(aq{0} is already installed\(aq.format(name)
+ return ret
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.IP 4. 3
+If step 2 found that changes \fIdo\fP need to be made, then check to see if the
+state was being run in test mode (i.e. with \fBtest=True\fP). If so, then exit
+with a \fBNone\fP result, a relevant comment, and (if possible) a \fBchanges\fP
+entry describing what changes would be made.
+.INDENT 3.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+if __opts__[\(aqtest\(aq]:
+ ret[\(aqresult\(aq] = None
+ ret[\(aqcomment\(aq] = \(aq{0} would be installed\(aq.format(name)
+ ret[\(aqchanges\(aq] = result
+ return ret
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.IP 5. 3
+Make the desired changes. This should again be done using a function from an
+accompanying execution module. If the result of that function is enough to
+tell you whether or not an error occurred, then you can exit with a
+\fBFalse\fP result and a relevant comment to explain what happened.
+.INDENT 3.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+result = __salt__[\(aqmodname.install\(aq](name)
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.IP 6. 3
+Perform the same check from step 2 again to confirm whether or not the
+minion is in the desired state. Just as in step 2, this function should be
+able to tell you by its return data whether or not changes need to be made.
+.INDENT 3.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+ret[\(aqchanges\(aq] = __salt__[\(aqmodname.check\(aq](name)
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+As you can see here, we are setting the \fBchanges\fP key in the return
+dictionary to the result of the \fBmodname.check\fP function (just as we did
+in step 4). The assumption here is that the information\-gathering function
+will return a dictionary explaining what changes need to be made. This may
+or may not fit your use case.
+.IP 7. 3
+Set the return data and return!
+.INDENT 3.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+if ret[\(aqchanges\(aq]:
+ ret[\(aqcomment\(aq] = \(aq{0} failed to install\(aq.format(name)
+else:
+ ret[\(aqresult\(aq] = True
+ ret[\(aqcomment\(aq] = \(aq{0} was installed\(aq.format(name)
+
+return ret
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.UNINDENT
.SS Using Custom State Modules
.sp
-Place your custom state modules inside a \fB_states\fP directory within the
-\fBfile_roots\fP specified by the master config file. These custom
-state modules can then be distributed in a number of ways. Custom state modules
-are distributed when \fBstate.apply\fP is run,
-or by executing the \fBsaltutil.sync_states\fP or \fBsaltutil.sync_all\fP functions.
+Before the state module can be used, it must be distributed to minions. This
+can be done by placing them into \fBsalt://_states/\fP\&. They can then be
+distributed manually to minions by running \fBsaltutil.sync_states\fP or \fBsaltutil.sync_all\fP\&. Alternatively, when running a
+highstate custom types will automatically be synced.
.sp
-Any custom states which have been synced to a minion, that are named the
-same as one of Salt\(aqs default set of states, will take the place of the default
-state with the same name. Note that a state\(aqs default name is its filename
-(i.e. \fBfoo.py\fP becomes state \fBfoo\fP), but that its name can be overridden
-by using a __virtual__ function\&.
+Any custom states which have been synced to a minion, that are named the same
+as one of Salt\(aqs default set of states, will take the place of the default
+state with the same name. Note that a state module\(aqs name defaults to one based
+on its filename (i.e. \fBfoo.py\fP becomes state module \fBfoo\fP), but that its
+name can be overridden by using a __virtual__ function\&.
.SS Cross Calling Execution Modules from States
.sp
As with Execution Modules, State Modules can also make use of the \fB__salt__\fP
@@ -46408,10 +53959,11 @@ The variable \fB__states__\fP is packed into the modules after they are loaded i
the Salt minion.
.sp
The \fB__states__\fP variable is a \fI\%Python dictionary\fP
-containing all of the state modules. Dictionary keys are strings representing the
-names of the modules and the values are the functions themselves.
+containing all of the state modules. Dictionary keys are strings representing
+the names of the modules and the values are the functions themselves.
.sp
-Salt state modules can be cross\-called by accessing the value in the \fB__states__\fP dict:
+Salt state modules can be cross\-called by accessing the value in the
+\fB__states__\fP dict:
.INDENT 0.0
.INDENT 3.5
.sp
@@ -47302,16 +54854,19 @@ state and an execution module. One good use case for utility modules is one
where it is necessary to invoke the same function from a custom outputter/returner, as well as an execution module.
.sp
Utility modules placed in \fBsalt://_utils/\fP will be synced to the minions when
-any of the following Salt functions are called:
+a highstate is run, as well as when any of the
+following Salt functions are called:
.INDENT 0.0
.IP \(bu 2
-\fBstate.apply\fP
-.IP \(bu 2
\fBsaltutil.sync_utils\fP
.IP \(bu 2
\fBsaltutil.sync_all\fP
.UNINDENT
.sp
+As of the Fluorine release, as well as 2017.7.7 and 2018.3.2 in their
+respective release cycles, the \fBsync\fP argument to \fBstate.apply\fP/\fBstate.sls\fP can
+be used to sync custom types when running individual SLS files.
+.sp
To sync to the Master, use either of the following:
.INDENT 0.0
.IP \(bu 2
@@ -48243,7 +55798,7 @@ following on the event bus:
.sp
.nf
.ft C
-salt/beacon/larry/inotify//etc/important_file {
+{
"_stamp": "2015\-09\-09T15:59:37.972753",
"data": {
"change": "IN_IGNORED",
@@ -49839,6 +57394,40 @@ cases.
Only one SLS target can be run at a time using this method, while using
\fBstate.sls\fP allows for multiple SLS files to
be passed in a comma\-separated list.
+.SH SOLARIS
+.sp
+This section contains details on Solaris specific quirks and workarounds.
+.sp
+\fBNOTE:\fP
+.INDENT 0.0
+.INDENT 3.5
+Solaris refers to both Solaris 10 comaptible platforms like Solaris 10, illumos, SmartOS, OmniOS, OpenIndiana,... and Oracle Solaris 11 platforms.
+.UNINDENT
+.UNINDENT
+.SS Solaris\-specific Behaviour
+.sp
+Salt is capable of managing Solaris systems, however due to various differences
+between the operating systems, there are some things you need to keep in mind.
+.sp
+This document will contain any quirks that apply across Salt or limitations in
+some modules.
+.SS FQDN/UQDN
+.sp
+On Solaris platforms the FQDN will not always be properly detected.
+If an IPv6 address is configured pythons \fB\(gasocket.getfqdn()\(ga\fP fails to return
+a FQDN and returns the nodename instead. For a full breakdown see the following
+issue on github: #37027
+.SS Grains
+.sp
+Not all grains are available or some have empty or 0 as value. Mostly grains
+that are depenend on hardware discovery like:
+\- num_gpus
+\- gpus
+.sp
+Also some resolver related grains like:
+\- domain
+\- \fI\%dns:options\fP
+\- \fI\%dns:sortlist\fP
.SH SALT SSH
.SS Getting Started
.sp
@@ -50257,6 +57846,372 @@ systems operation.
.sp
If you need a persistent Salt environment, for instance to set persistent grains,
this value will need to be changed.
+.SH THORIUM COMPLEX REACTOR
+.sp
+\fBNOTE:\fP
+.INDENT 0.0
+.INDENT 3.5
+Thorium is a provisional feature of Salt and is subject to change
+and removal if the feature proves to not be a viable solution.
+.UNINDENT
+.UNINDENT
+.sp
+\fBNOTE:\fP
+.INDENT 0.0
+.INDENT 3.5
+Thorium was added to Salt as an experimental feature in the 2016.3.0
+release, as of 2016.3.0 this feature is considered experimental, no
+guarantees are made for support of any kind yet.
+.UNINDENT
+.UNINDENT
+.sp
+The original Salt Reactor is based on the idea of listening for a specific
+event and then reacting to it. This model comes with many logical limitations,
+for instance it is very difficult (and hacky) to fire a reaction based on
+aggregate data or based on multiple events.
+.sp
+The Thorium reactor is intended to alleviate this problem in a very elegant way.
+Instead of using extensive jinja routines or complex python sls files the
+aggregation of data and the determination of what should run becomes isolated
+to the sls data logic, makes the definitions much cleaner.
+.SS Starting the Thorium Engine
+.sp
+To enable the thorium engine add the following configuration to the engines
+section of your Salt Master or Minion configuration file and restart the daemon:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+engines:
+ \- thorium: {}
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.SS Thorium Modules
+.sp
+Because of its specialized nature, Thorium uses its own set of modules. However,
+many of these modules are designed to wrap the more commonly\-used Salt
+subsystems. These modules are:
+.INDENT 0.0
+.IP \(bu 2
+local: Execution modules
+.IP \(bu 2
+runner: Runner modules
+.IP \(bu 2
+wheel: Wheel modules
+.UNINDENT
+.sp
+There are other modules that ship with Thorium as well. Some of these will be
+highlighted later in this document.
+.SS Writing Thorium Formulas
+.sp
+Like some other Salt subsystems, Thorium uses its own directory structure. The
+default location for this structure is \fB/srv/thorium/\fP, but it can be changed
+using the \fBthorium_roots\fP setting in the \fBmaster\fP configuration file.
+.sp
+Example \fBthorium_roots\fP configuration:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+thorium_roots:
+ base:
+ \- /etc/salt/thorium
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.SS The Thorium top.sls File
+.sp
+Thorium uses its own \fBtop.sls\fP file, which follows the same convention as is
+found in \fB/srv/salt/\fP:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+:
+ :
+ \-
+ \-
+ \-
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+For instance, a \fBtop.sls\fP using a standard \fBbase\fP environment and a single
+Thorium formula called \fBkey_clean\fP, would look like:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+base:
+ \(aq*\(aq:
+ \- key_clean
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Take note that the target in a Thorium \fBtop.sls\fP is not used; it only exists
+to follow the same convention as other \fBtop.sls\fP files. Leave this set to
+\fB\(aq*\(aq\fP in your own Thorium \fBtop.sls\fP\&.
+.SS Thorium Formula Files
+.sp
+Thorium SLS files are processed by the same state compiler that processes Salt
+state files. This means that features like requisites, templates, and so on are
+available.
+.sp
+Let\(aqs take a look at an example, and then discuss each component of it. This
+formula uses Thorium to detect when a minion has disappeared and then deletes
+the key from the master when the minion has been gone for 60 seconds:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+statreg:
+ status.reg
+
+keydel:
+ key.timeout:
+ \- delete: 60
+ \- require:
+ \- status: startreg
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+There are two stanzas in this formula, whose IDs are \fBstatreg\fP and
+\fBkeydel\fP\&. The first stanza, \fBstatreg\fP, tells Thorium to keep track of
+minion status beacons in its \fIregister\fP\&. We\(aqll talk more about the register in
+a moment.
+.sp
+The second stanza, \fBkeydel\fP, is the one that does the real work. It uses the
+\fBkey\fP module to apply an expiration (using the \fBtimeout\fP function) to a
+minion. Because \fBdelete\fP is set to \fB60\fP, this is a 60 second expiration. If
+a minion does not check in at least once every 60 seconds, its key will be
+deleted from the master. This particular function also allows you to use
+\fBreject\fP instead of \fBdelete\fP, allowing for a minion to be rejected instead
+of deleted if it does not check in within the specified time period.
+.sp
+There is also a \fBrequire\fP requisite in this stanza. It states that the
+\fBkey.timeout\fP function will not be called unless the \fBstatus.reg\fP function
+in the \fBstatreg\fP codeblock has been successfully called first.
+.SS Thorium Links to Beacons
+.sp
+The above example was added in the 2016.11.0 release of Salt and makes use of the
+\fBstatus\fP beacon also added in the 2016.11.0 release. For the above Thorium state
+to function properly you will also need to enable the \fBstatus\fP beacon in the
+\fBminion\fP configuration file:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+beacons:
+ status:
+ \- interval: 10
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+This will cause the minion to use the status beacon to check in with the master
+every 10 seconds.
+.SS The Thorium Register
+.sp
+In order to keep track of information, Thorium uses an in\-memory register (or
+rather, collection of registers) on the master. These registers are only
+populated when told to by a formula, and they normally will be erased when the
+master is restarted. It is possible to persist the registers to disk, but we\(aqll
+get to that in a moment.
+.sp
+The example above uses \fBstatus.reg\fP to populate a register for you, which is
+automatically used by the \fBkey.timeout\fP function. However, you can set your
+own register values as well, using the \fBreg\fP module.
+.sp
+Because Thorium watches the event bus, the \fBreg\fP module is designed to look
+for user\-specified tags, and then extract data from the payload of events that
+match those tags. For instance, the following stanza will look for an event
+with a tag of \fBmy/custom/event\fP:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+foo:
+ reg.list:
+ \- add: bar
+ \- match: my/custom/event
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+When such an event is found, the data found in the payload dictionary key of
+\fBbar\fP will be stored in a register called \fBfoo\fP\&. This register will store
+that data in a \fBlist\fP\&. You may also use \fBreg.set\fP to add data to a \fBset()\fP
+instead.
+.sp
+If you would like to see a copy of the register as it is stored in memory, you
+can use the \fBfile.save\fP function:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+myreg:
+ file.save
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+In this case, each time the register is updated, a copy will be saved in JSON
+format at \fB/var/cache/salt/master/thorium/saves/myreg\fP\&. If you would like to
+see when particular events are added to a list\-type register, you may add a
+\fBstamp\fP option to \fBreg.list\fP (but not \fBreg.set\fP). With the above two
+stanzas put together, this would look like:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+foo:
+ reg.list:
+ \- add: bar
+ \- match: my/custom/event
+ \- stamp: True
+
+myreg:
+ file.save
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+If you would like to only keep a certain number of the most recent register
+entries, you may also add a \fBprune\fP option to \fBreg.list\fP (but not
+\fBreg.set\fP):
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+foo:
+ reg.list:
+ \- add: bar
+ \- match: my/custom/event
+ \- stamp: True
+ \- prune: 50
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+This example will only keep the 50 most recent entries in the \fBfoo\fP register.
+.SS Using Register Data
+.sp
+Putting data in a register is useless if you don\(aqt do anything with it. The
+\fBcheck\fP module is designed to examine register data and determine whether it
+matches the given parameters. For instance, the \fBcheck.contains\fP function
+will return \fBTrue\fP if the given \fBvalue\fP is contained in the specified
+register:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+foo:
+ reg.list:
+ \- add: bar
+ \- match: my/custom/event
+ \- stamp: True
+ \- prune: 50
+ check.contains:
+ \- value: somedata
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Used with a \fBrequire\fP requisite, we can call one of the wrapper modules and
+perform an operation. For example:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+shell_test:
+ local.cmd:
+ \- tgt: dufresne
+ \- func: cmd.run
+ \- arg:
+ \- echo \(aqthorium success\(aq > /tmp/thorium.txt
+ \- require:
+ \- check: foo
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+This stanza will only run if the \fBcheck.contains\fP function under the \fBfoo\fP
+ID returns true (meaning the match was found).
+.sp
+There are a number of other functions in the \fBcheck\fP module which use
+different means of comparing values:
+.INDENT 0.0
+.IP \(bu 2
+\fBgt\fP: Check whether the register entry is greater than the given value
+.IP \(bu 2
+\fBgte\fP: Check whether the register entry is greater than or equal to the given value
+.IP \(bu 2
+\fBlt\fP: Check whether the register entry is less than the given value
+.IP \(bu 2
+\fBlte\fP: Check whether the register entry is less than or equal to the given value
+.IP \(bu 2
+\fBeq\fP: Check whether the register entry is equal to the given value
+.IP \(bu 2
+\fBne\fP: Check whether the register entry is not equal to the given value
+.UNINDENT
+.sp
+There is also a function called \fBcheck.event\fP which does not examine the
+register. Instead, it looks directly at an event as it is coming in on the
+event bus, and returns \fBTrue\fP if that event\(aqs tag matches. For example:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+salt/foo/*/bar:
+ check.event
+
+run_remote_ex:
+ local.cmd:
+ \- tgt: \(aq*\(aq
+ \- func: test.ping
+ \- require:
+ \- check: salt/foo/*/bar
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+This formula will look for an event whose tag is \fBsalt/foo//bar\fP and
+if it comes in, issue a \fBtest.ping\fP to all minions.
+.SS Register Persistence
+.sp
+It is possible to persist the register data to disk when a master is stopped
+gracefully, and reload it from disk when the master starts up again. This
+functionality is provided by the returner subsystem, and is enabled whenever
+any returner containing a \fBload_reg\fP and a \fBsave_reg\fP function is used.
.SH SALT CLOUD
.SS Configuration
.sp
@@ -50673,10 +58628,10 @@ salt\-cloud \-m /path/to/cloud.map \-Q
.UNINDENT
.SS See also
.sp
-\fBsalt\-cloud(7)\fP
-\fBsalt(7)\fP
-\fBsalt\-master(1)\fP
-\fBsalt\-minion(1)\fP
+\fIsalt\-cloud(7)\fP
+\fIsalt(7)\fP
+\fIsalt\-master(1)\fP
+\fIsalt\-minion(1)\fP
.SS Salt Cloud basic usage
.sp
Salt Cloud needs, at least, one configured
@@ -55150,18 +63105,10 @@ one of the public cloud instances or as a private instance on premises.
.sp
\fI\%http://cloud.dimensiondata.com/\fP
.sp
-CaaS has its own non\-standard
-.nf
-\(gaAPI\(ga_
-.fi
- , SaltStack provides a
-wrapper on top of this
-.nf
-\(gaAPI\(ga_
-.fi
- with common methods with other IaaS solutions and
-Public cloud providers. Therefore, you can use the Dimension Data
-module to communicate with both the public and private clouds.
+CaaS has its own non\-standard API , SaltStack provides a wrapper on top of this
+API with common methods with other IaaS solutions and Public cloud providers.
+Therefore, you can use the Dimension Data module to communicate with both the
+public and private clouds.
.SS Dependencies
.sp
This driver requires the Python \fBapache\-libcloud\fP and \fBnetaddr\fP library to be installed.
@@ -55216,14 +63163,13 @@ my\-dimensiondata\-config:
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
-Changed in version 2015.8.0.
-
-.sp
-The \fBprovider\fP parameter in cloud provider definitions was renamed to \fBdriver\fP\&. This
-change was made to avoid confusion with the \fBprovider\fP parameter that is used in cloud profile
-definitions. Cloud provider definitions now use \fBdriver\fP to refer to the Salt cloud module that
-provides the underlying functionality to connect to a cloud host, while cloud profiles continue
-to use \fBprovider\fP to refer to provider configurations that you define.
+In version 2015.8.0, the \fBprovider\fP parameter in cloud provider
+definitions was renamed to \fBdriver\fP\&. This change was made to avoid
+confusion with the \fBprovider\fP parameter that is used in cloud profile
+definitions. Cloud provider definitions now use \fBdriver\fP to refer to the
+Salt cloud module that provides the underlying functionality to connect to
+a cloud host, while cloud profiles continue to use \fBprovider\fP to refer to
+provider configurations that you define.
.UNINDENT
.UNINDENT
.SS Profiles
@@ -58374,7 +66320,7 @@ at \fB/etc/salt/cloud.profiles\fP or in the \fB/etc/salt/cloud.profiles.d/\fP di
.ft C
linode_1024:
provider: my\-linode\-config
- size: Linode 2048
+ size: Linode 2GB
image: CentOS 7
location: London, England, UK
.ft P
@@ -58423,12 +66369,14 @@ my\-linode\-config:
\-\-\-\-\-\-\-\-\-\-
linode:
\-\-\-\-\-\-\-\-\-\-
- Linode 1024:
+ Linode 2GB:
\-\-\-\-\-\-\-\-\-\-
AVAIL:
\-\-\-\-\-\-\-\-\-\-
10:
500
+ 11:
+ 500
2:
500
3:
@@ -58446,11 +66394,19 @@ my\-linode\-config:
CORES:
1
DISK:
- 24
+ 50
HOURLY:
0.015
LABEL:
- Linode 1024
+ Linode 2GB
+ PLANID:
+ 2
+ PRICE:
+ 10.0
+ RAM:
+ 2048
+ XFER:
+ 2000
\&...SNIP...
.ft P
.fi
@@ -60219,12 +68175,14 @@ More information can be found on Proxmox API under the \(aqPOST\(aq method of /n
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
-The Proxmox API offers a lot more options and parameters, which are not yet supported by this salt\-cloud \(aqoverlay\(aq. Feel free to add your contribution by forking the github repository and modifying the following file: salt/salt/cloud/clouds/proxmox.py
-An easy way to support more parameters for VM creation would be to add the names of the optional parameters in the \(aqcreate_nodes(
-.nf
-vm_
-.fi
-)\(aq function, under the \(aqqemu\(aq technology. But it requires you to dig into the code ...
+The Proxmox API offers a lot more options and parameters, which are not yet
+supported by this salt\-cloud \(aqoverlay\(aq. Feel free to add your contribution
+by forking the github repository and modifying the following file:
+\fBsalt/cloud/clouds/proxmox.py\fP
+.sp
+An easy way to support more parameters for VM creation would be to add the
+names of the optional parameters in the \(aqcreate_nodes(vm_)\(aq function, under
+the \(aqqemu\(aq technology. But it requires you to dig into the code ...
.UNINDENT
.UNINDENT
.SS Getting Started With Rackspace
@@ -61754,7 +69712,7 @@ virtualbox\-test:
.UNINDENT
.INDENT 0.0
.TP
-\fBclonefrom\fP \fBMandatory\fP
+.B \fBclonefrom\fP \fBMandatory\fP
Enter the name of the VM/template to clone from.
.UNINDENT
.sp
@@ -62041,18 +69999,19 @@ Enter the number of vCPUS that you want the VM/template to have. If not specifie
the current VM/template\(aqs vCPU count is used.
.TP
.B \fBcores_per_socket\fP
-New in version 2016.11.0.
-
-.sp
Enter the number of cores per vCPU that you want the VM/template to have. If not specified,
this will default to 1.
.sp
\fBNOTE:\fP
.INDENT 7.0
.INDENT 3.5
-Cores per socket should be less than or equal to the total number of vCPUs assigned to the VM/template.
+Cores per socket should be less than or equal to the total number of
+vCPUs assigned to the VM/template.
.UNINDENT
.UNINDENT
+.sp
+New in version 2016.11.0.
+
.TP
.B \fBmemory\fP
Enter the memory size (in MB or GB) that you want the VM/template to have. If
@@ -62717,7 +70676,7 @@ This has also been tested to work with pipes, if needed:
.sp
.nf
.ft C
-script_args: | head
+script_args: \(aq| head\(aq
.ft P
.fi
.UNINDENT
@@ -64152,7 +72111,7 @@ This has also been tested to work with pipes, if needed:
.sp
.nf
.ft C
-script_args: | head
+script_args: \(aq| head\(aq
.ft P
.fi
.UNINDENT
@@ -66672,11 +74631,7 @@ when designing a proxy module flexible enough to open the
connection with the remote device only when required.
.SS New in 2016.11.0
.sp
-Proxy minions now support configuration files with names ending in \(aq
-.nf
-*
-.fi
-\&.conf\(aq
+Proxy minions now support configuration files with names ending in \(aq*.conf\(aq
and placed in /etc/salt/proxy.d.
.sp
Proxy minions can now be configured in /etc/salt/proxy or /etc/salt/proxy.d
@@ -67043,7 +74998,7 @@ Pre 2015.8 the proxymodule also must have an \fBid()\fP function. 2015.8 and fo
this function because the proxy\(aqs id is required on the command line.
.sp
Here is an example proxymodule used to interface to a \fIvery\fP simple REST
-server. Code for the server is in the \fI\%salt\-contrib GitHub repository\fP
+server. Code for the server is in the \fI\%salt\-contrib GitHub repository\fP\&.
.sp
This proxymodule enables "service" enumeration, starting, stopping, restarting,
and status; "package" installation, and a ping.
@@ -67500,7 +75455,7 @@ This sections specifically talks about the SSH proxy module and
explains the working of the example proxy module \fBssh_sample\fP\&.
.sp
Here is a simple example proxymodule used to interface to a device over SSH.
-Code for the SSH shell is in the \fI\%salt\-contrib GitHub repository\fP
+Code for the SSH shell is in the \fI\%salt\-contrib GitHub repository\fP\&.
.sp
This proxymodule enables "package" installation.
.INDENT 0.0
@@ -68003,606 +75958,6 @@ salt p8000 pkg.list_pkgs
.fi
.UNINDENT
.UNINDENT
-.SS ESXi Proxy Minion
-.sp
-New in version 2015.8.4.
-
-.sp
-\fBNOTE:\fP
-.INDENT 0.0
-.INDENT 3.5
-This tutorial assumes basic knowledge of Salt. To get up to speed, check
-out the Salt Walkthrough\&.
-.sp
-This tutorial also assumes a basic understanding of Salt Proxy Minions. If
-you\(aqre unfamiliar with Salt\(aqs Proxy Minion system, please read the
-Salt Proxy Minion documentation and the
-Salt Proxy Minion End\-to\-End Example
-tutorial.
-.sp
-The third assumption that this tutorial makes is that you also have a
-basic understanding of ESXi hosts. You can learn more about ESXi hosts on
-\fI\%VMware\(aqs various resources\fP\&.
-.UNINDENT
-.UNINDENT
-.sp
-Salt\(aqs ESXi Proxy Minion allows a VMware ESXi host to be treated as an individual
-Salt Minion, without installing a Salt Minion on the ESXi host.
-.sp
-Since an ESXi host may not necessarily run on an OS capable of hosting a Python
-stack, the ESXi host can\(aqt run a regular Salt Minion directly. Therefore, Salt\(aqs
-Proxy Minion functionality enables you to designate another machine to host a
-proxy process that "proxies" communication from the Salt Master to the ESXi host.
-The master does not know or care that the ESXi target is not a "real" Salt Minion.
-.sp
-More in\-depth conceptual reading on Proxy Minions can be found in the
-Proxy Minion section of Salt\(aqs documentation.
-.sp
-Salt\(aqs ESXi Proxy Minion was added in the 2015.8.4 release of Salt.
-.sp
-\fBNOTE:\fP
-.INDENT 0.0
-.INDENT 3.5
-Be aware that some functionality for the ESXi Proxy Minion may depend on the
-type of license attached the ESXi host(s).
-.sp
-For example, certain services are only available to manipulate service state
-or policies with a VMware vSphere Enterprise or Enterprise Plus license, while
-others are available with a Standard license. The \fBntpd\fP service is restricted
-to an Enterprise Plus license, while \fBssh\fP is available via the Standard
-license.
-.sp
-Please see the \fI\%vSphere Comparison\fP page for more information.
-.UNINDENT
-.UNINDENT
-.SS Dependencies
-.sp
-Manipulation of the ESXi host via a Proxy Minion requires the machine running
-the Proxy Minion process to have the ESXCLI package (and all of it\(aqs dependencies)
-and the pyVmomi Python Library to be installed.
-.SS ESXi Password
-.sp
-The ESXi Proxy Minion uses VMware\(aqs API to perform tasks on the host as if it was
-a regular Salt Minion. In order to access the API that is already running on the
-ESXi host, the ESXi host must have a username and password that is used to log
-into the host. The username is usually \fBroot\fP\&. Before Salt can access the ESXi
-host via VMware\(aqs API, a default password \fImust\fP be set on the host.
-.SS pyVmomi
-.sp
-The pyVmomi Python library must be installed on the machine that is running the
-proxy process. pyVmomi can be installed via pip:
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-pip install pyVmomi
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-\fBNOTE:\fP
-.INDENT 0.0
-.INDENT 3.5
-Version 6.0 of pyVmomi has some problems with SSL error handling on certain
-versions of Python. If using version 6.0 of pyVmomi, the machine that you
-are running the proxy minion process from must have either Python 2.6,
-Python 2.7.9, or newer. This is due to an upstream dependency in pyVmomi 6.0
-that is not supported in Python version 2.7 to 2.7.8. If the
-version of Python running the proxy process is not in the supported range, you
-will need to install an earlier version of pyVmomi. See \fI\%Issue #29537\fP for
-more information.
-.UNINDENT
-.UNINDENT
-.sp
-Based on the note above, to install an earlier version of pyVmomi than the
-version currently listed in PyPi, run the following:
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-pip install pyVmomi==5.5.0.2014.1.1
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-The 5.5.0.2014.1.1 is a known stable version that the original ESXi Proxy Minion
-was developed against.
-.SS ESXCLI
-.sp
-Currently, about a third of the functions used for the ESXi Proxy Minion require
-the ESXCLI package be installed on the machine running the Proxy Minion process.
-.sp
-The ESXCLI package is also referred to as the VMware vSphere CLI, or vCLI. VMware
-provides vCLI package installation instructions for \fI\%vSphere 5.5\fP and
-\fI\%vSphere 6.0\fP\&.
-.sp
-Once all of the required dependencies are in place and the vCLI package is
-installed, you can check to see if you can connect to your ESXi host by running
-the following command:
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-esxcli \-s \-u \-p system syslog config get
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-If the connection was successful, ESXCLI was successfully installed on your system.
-You should see output related to the ESXi host\(aqs syslog configuration.
-.SS Configuration
-.sp
-There are several places where various configuration values need to be set in
-order for the ESXi Proxy Minion to run and connect properly.
-.SS Proxy Config File
-.sp
-On the machine that will be running the Proxy Minon process(es), a proxy config
-file must be in place. This file should be located in the \fB/etc/salt/\fP directory
-and should be named \fBproxy\fP\&. If the file is not there by default, create it.
-.sp
-This file should contain the location of your Salt Master that the Salt Proxy
-will connect to.
-.sp
-Example Proxy Config File:
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-# /etc/salt/proxy
-
-master:
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.SS Pillar Profiles
-.sp
-Proxy minions get their configuration from Salt\(aqs Pillar. Every proxy must
-have a stanza in Pillar and a reference in the Pillar top\-file that matches
-the Proxy ID. At a minimum for communication with the ESXi host, the pillar
-should look like this:
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-proxy:
- proxytype: esxi
- host:
- username:
- passwords:
- \- first_password
- \- second_password
- \- third_password
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-Some other optional settings are \fBprotocol\fP and \fBport\fP\&. These can be added
-to the pillar configuration.
-.SS proxytype
-.sp
-The \fBproxytype\fP key and value pair is critical, as it tells Salt which
-interface to load from the \fBproxy\fP directory in Salt\(aqs install hierarchy,
-or from \fB/srv/salt/_proxy\fP on the Salt Master (if you have created your
-own proxy module, for example). To use this ESXi Proxy Module, set this to
-\fBesxi\fP\&.
-.SS host
-.sp
-The location, or ip/dns, of the ESXi host. Required.
-.SS username
-.sp
-The username used to login to the ESXi host, such as \fBroot\fP\&. Required.
-.SS passwords
-.sp
-A list of passwords to be used to try and login to the ESXi host. At least
-one password in this list is required.
-.sp
-The proxy integration will try the passwords listed in order. It is
-configured this way so you can have a regular password and the password you
-may be updating for an ESXi host either via the
-\fBvsphere.update_host_password\fP
-execution module function or via the
-\fBesxi.password_present\fP state
-function. This way, after the password is changed, you should not need to
-restart the proxy minion\-\-it should just pick up the new password
-provided in the list. You can then change pillar at will to move that
-password to the front and retire the unused ones.
-.sp
-Use\-case/reasoning for using a list of passwords: You are setting up an
-ESXi host for the first time, and the host comes with a default password.
-You know that you\(aqll be changing this password during your initial setup
-from the default to a new password. If you only have one password option,
-and if you have a state changing the password, any remote execution commands
-or states that run after the password change will not be able to run on the
-host until the password is updated in Pillar and the Proxy Minion process is
-restarted.
-.sp
-This allows you to use any number of potential fallback passwords.
-.sp
-\fBNOTE:\fP
-.INDENT 0.0
-.INDENT 3.5
-When a password is changed on the host to one in the list of possible
-passwords, the further down on the list the password is, the longer
-individual commands will take to return. This is due to the nature of
-pyVmomi\(aqs login system. We have to wait for the first attempt to fail
-before trying the next password on the list.
-.sp
-This scenario is especially true, and even slower, when the proxy
-minion first starts. If the correct password is not the first password
-on the list, it may take up to a minute for \fBtest.ping\fP to respond
-with a \fBTrue\fP result. Once the initial authorization is complete, the
-responses for commands will be a little faster.
-.sp
-To avoid these longer waiting periods, SaltStack recommends moving the
-correct password to the top of the list and restarting the proxy minion
-at your earliest convenience.
-.UNINDENT
-.UNINDENT
-.SS protocol
-.sp
-If the ESXi host is not using the default protocol, set this value to an
-alternate protocol. Default is \fBhttps\fP\&. For example:
-.SS port
-.sp
-If the ESXi host is not using the default port, set this value to an
-alternate port. Default is \fB443\fP\&.
-.SS Example Configuration Files
-.sp
-An example of all of the basic configurations that need to be in place before
-starting the Proxy Minion processes includes the Proxy Config File, Pillar
-Top File, and any individual Proxy Minion Pillar files.
-.sp
-In this example, we\(aqll assuming there are two ESXi hosts to connect to. Therefore,
-we\(aqll be creating two Proxy Minion config files, one config for each ESXi host.
-.sp
-Proxy Config File:
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-# /etc/salt/proxy
-
-master:
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-Pillar Top File:
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-# /srv/pillar/top.sls
-
-base:
- \(aqesxi\-1\(aq:
- \- esxi\-1
- \(aqesxi\-2\(aq:
- \- esxi\-2
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-Pillar Config File for the first ESXi host, esxi\-1:
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-# /srv/pillar/esxi\-1.sls
-
-proxy:
- proxytype: esxi
- host: esxi\-1.example.com
- username: \(aqroot\(aq
- passwords:
- \- bad\-password\-1
- \- backup\-bad\-password\-1
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-Pillar Config File for the second ESXi host, esxi\-2:
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-# /srv/pillar/esxi\-2.sls
-
-proxy:
- proxytype: esxi
- host: esxi\-2.example.com
- username: \(aqroot\(aq
- passwords:
- \- bad\-password\-2
- \- backup\-bad\-password\-2
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.SS Starting the Proxy Minion
-.sp
-Once all of the correct configuration files are in place, it is time to start the
-proxy processes!
-.INDENT 0.0
-.IP 1. 3
-First, make sure your Salt Master is running.
-.IP 2. 3
-Start the first Salt Proxy, in debug mode, by giving the Proxy Minion process
-and ID that matches the config file name created in the \fI\%Configuration\fP section.
-.UNINDENT
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-salt\-proxy \-\-proxyid=\(aqesxi\-1\(aq \-l debug
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.INDENT 0.0
-.IP 1. 3
-Accept the \fBesxi\-1\fP Proxy Minion\(aqs key on the Salt Master:
-.UNINDENT
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-# salt\-key \-L
-Accepted Keys:
-Denied Keys:
-Unaccepted Keys:
-esxi\-1
-Rejected Keys:
-#
-# salt\-key \-a esxi\-1
-The following keys are going to be accepted:
-Unaccepted Keys:
-esxi\-1
-Proceed? [n/Y] y
-Key for minion esxi\-1 accepted.
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.INDENT 0.0
-.IP 1. 3
-Repeat for the second Salt Proxy, this time we\(aqll run the proxy process as a
-daemon, as an example.
-.UNINDENT
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-salt\-proxy \-\-proxyid=\(aqesxi\-2\(aq \-d
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.INDENT 0.0
-.IP 1. 3
-Accept the \fBesxi\-2\fP Proxy Minion\(aqs key on the Salt Master:
-.UNINDENT
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-# salt\-key \-L
-Accepted Keys:
-esxi\-1
-Denied Keys:
-Unaccepted Keys:
-esxi\-2
-Rejected Keys:
-#
-# salt\-key \-a esxi\-1
-The following keys are going to be accepted:
-Unaccepted Keys:
-esxi\-2
-Proceed? [n/Y] y
-Key for minion esxi\-1 accepted.
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.INDENT 0.0
-.IP 1. 3
-Check and see if your Proxy Minions are responding:
-.UNINDENT
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-# salt \(aqesxi\-*\(aq test.ping
-esxi\-1:
- True
-esxi\-3:
- True
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.SS Executing Commands
-.sp
-Now that you\(aqve configured your Proxy Minions and have them responding successfully
-to a \fBtest.ping\fP, we can start executing commands against the ESXi hosts via Salt.
-.sp
-It\(aqs important to understand how this particular proxy works, and there are a couple
-of important pieces to be aware of in order to start running remote execution and
-state commands against the ESXi host via a Proxy Minion: the
-\fI\%vSphere Execution Module\fP, the \fI\%ESXi Execution Module\fP, and the \fI\%ESXi State Module\fP\&.
-.SS vSphere Execution Module
-.sp
-The \fBSalt.modules.vsphere\fP is a
-standard Salt execution module that does the bulk of the work for the ESXi Proxy
-Minion. If you pull up the docs for it you\(aqll see that almost every function in
-the module takes credentials (\fBusername\fP and \fBpassword\fP) and a target \fBhost\fP
-argument. When credentials and a host aren\(aqt passed, Salt runs commands
-through \fBpyVmomi\fP or \fBESXCLI\fP against the local machine. If you wanted,
-you could run functions from this module on any machine where an appropriate
-version of \fBpyVmomi\fP and \fBESXCLI\fP are installed, and that machine would reach
-out over the network and communicate with the ESXi host.
-.sp
-You\(aqll notice that most of the functions in the vSphere module require a \fBhost\fP,
-\fBusername\fP, and \fBpassword\fP\&. These parameters are contained in the Pillar files and
-passed through to the function via the proxy process that is already running. You don\(aqt
-need to provide these parameters when you execute the commands. See the
-\fI\%Running Remote Execution Commands\fP section below for an example.
-.SS ESXi Execution Module
-.sp
-In order for the Pillar information set up in the \fI\%Configuration\fP section above to
-be passed to the function call in the vSphere Execution Module, the
-\fBsalt.modules.esxi\fP execution module acts
-as a "shim" between the vSphere execution module functions and the proxy process.
-.sp
-The "shim" takes the authentication credentials specified in the Pillar files and
-passes them through to the \fBhost\fP, \fBusername\fP, \fBpassword\fP, and optional
-\fBprotocol\fP and \fBport\fP options required by the vSphere Execution Module functions.
-.sp
-If the function takes more positional, or keyword, arguments you can append them
-to the call. It\(aqs this shim that speaks to the ESXi host through the proxy, arranging
-for the credentials and hostname to be pulled from the Pillar section for the ESXi
-Proxy Minion.
-.sp
-Because of the presence of the shim, to lookup documentation for what
-functions you can use to interface with the ESXi host, you\(aqll want to
-look in \fBsalt.modules.vsphere\fP
-instead of \fBsalt.modules.esxi\fP\&.
-.SS Running Remote Execution Commands
-.sp
-To run commands from the Salt Master to execute, via the ESXi Proxy Minion, against
-the ESXi host, you use the \fBesxi.cmd \fP syntax to call
-functions located in the vSphere Execution Module. Both args and kwargs needed
-for various vsphere execution module functions must be passed through in a kwarg\-
-type manor. For example:
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-salt \(aqesxi\-*\(aq esxi.cmd system_info
-salt \(aqexsi\-*\(aq esxi.cmd get_service_running service_name=\(aqssh\(aq
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.SS ESXi State Module
-.sp
-The ESXi State Module functions similarly to other state modules. The "shim" provided
-by the \fI\%ESXi Execution Module\fP passes the necessary \fBhost\fP, \fBusername\fP, and
-\fBpassword\fP credentials through, so those options don\(aqt need to be provided in the
-state. Other than that, state files are written and executed just like any other
-Salt state. See the \fBsalt.modules.esxi\fP state
-for ESXi state functions.
-.sp
-The follow state file is an example of how to configure various pieces of an ESXi host
-including enabling SSH, uploading and SSH key, configuring a coredump network config,
-syslog, ntp, enabling VMotion, resetting a host password, and more.
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-# /srv/salt/configure\-esxi.sls
-
-configure\-host\-ssh:
- esxi.ssh_configured:
- \- service_running: True
- \- ssh_key_file: /etc/salt/ssh_keys/my_key.pub
- \- service_policy: \(aqautomatic\(aq
- \- service_restart: True
- \- certificate_verify: True
-
-configure\-host\-coredump:
- esxi.coredump_configured:
- \- enabled: True
- \- dump_ip: \(aqmy\-coredump\-ip.example.com\(aq
-
-configure\-host\-syslog:
- esxi.syslog_configured:
- \- syslog_configs:
- loghost: ssl://localhost:5432,tcp://10.1.0.1:1514
- default\-timeout: 120
- \- firewall: True
- \- reset_service: True
- \- reset_syslog_config: True
- \- reset_configs: loghost,default\-timeout
-
-configure\-host\-ntp:
- esxi.ntp_configured:
- \- service_running: True
- \- ntp_servers:
- \- 192.174.1.100
- \- 192.174.1.200
- \- service_policy: \(aqautomatic\(aq
- \- service_restart: True
-
-configure\-vmotion:
- esxi.vmotion_configured:
- \- enabled: True
-
-configure\-host\-vsan:
- esxi.vsan_configured:
- \- enabled: True
- \- add_disks_to_vsan: True
-
-configure\-host\-password:
- esxi.password_present:
- \- password: \(aqnew\-bad\-password\(aq
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-States are called via the ESXi Proxy Minion just as they would on a regular minion.
-For example:
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-salt \(aqesxi\-*\(aq state.sls configure\-esxi test=true
-salt \(aqesxi\-*\(aq state.sls configure\-esxi
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.SS Relevant Salt Files and Resources
-.INDENT 0.0
-.IP \(bu 2
-\fBESXi Proxy Minion\fP
-.IP \(bu 2
-\fBESXi Execution Module\fP
-.IP \(bu 2
-\fBESXi State Module\fP
-.IP \(bu 2
-Salt Proxy Minion Docs
-.IP \(bu 2
-Salt Proxy Minion End\-to\-End Example
-.IP \(bu 2
-\fBvSphere Execution Module\fP
-.UNINDENT
.SH SALT VIRT
.sp
The Salt Virt cloud controller capability was initially added to Salt in
@@ -68831,482 +76186,6 @@ virt.nic:
This configuration allows for one of six profiles to be selected, allowing
virtual machines to be created which attach to different network depending
on the needs of the deployed vm.
-.SS Salt as a Cloud Controller
-.sp
-In Salt 0.14.0, an advanced cloud control system were introduced, allow
-private cloud vms to be managed directly with Salt. This system is generally
-referred to as \fBSalt Virt\fP\&.
-.sp
-The Salt Virt system already exists and is installed within Salt itself, this
-means that besides setting up Salt, no additional salt code needs to be
-deployed.
-.sp
-\fBNOTE:\fP
-.INDENT 0.0
-.INDENT 3.5
-The \fBlibvirt\fP python module and the \fBcerttool\fP binary are required.
-.UNINDENT
-.UNINDENT
-.sp
-The main goal of Salt Virt is to facilitate a very fast and simple cloud. The
-cloud that can scale and is fully featured. Salt Virt comes with the
-ability to set up and manage complex virtual machine networking, powerful
-image and disk management, as well as virtual machine migration with and without
-shared storage.
-.sp
-This means that Salt Virt can be used to create a cloud from a blade center
-and a SAN, but can also create a cloud out of a swarm of Linux Desktops
-without a single shared storage system. Salt Virt can make clouds from
-truly commodity hardware, but can also stand up the power of specialized
-hardware as well.
-.SS Setting up Hypervisors
-.sp
-The first step to set up the hypervisors involves getting the correct software
-installed and setting up the hypervisor network interfaces.
-.SS Installing Hypervisor Software
-.sp
-Salt Virt is made to be hypervisor agnostic but currently the only fully
-implemented hypervisor is KVM via libvirt.
-.sp
-The required software for a hypervisor is libvirt and kvm. For advanced
-features install libguestfs or qemu\-nbd.
-.sp
-\fBNOTE:\fP
-.INDENT 0.0
-.INDENT 3.5
-Libguestfs and qemu\-nbd allow for virtual machine images to be mounted
-before startup and get pre\-seeded with configurations and a salt minion
-.UNINDENT
-.UNINDENT
-.sp
-This sls will set up the needed software for a hypervisor, and run the routines
-to set up the libvirt pki keys.
-.sp
-\fBNOTE:\fP
-.INDENT 0.0
-.INDENT 3.5
-Package names and setup used is Red Hat specific, different package names
-will be required for different platforms
-.UNINDENT
-.UNINDENT
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-libvirt:
- pkg.installed: []
- file.managed:
- \- name: /etc/sysconfig/libvirtd
- \- contents: \(aqLIBVIRTD_ARGS="\-\-listen"\(aq
- \- require:
- \- pkg: libvirt
- virt.keys:
- \- require:
- \- pkg: libvirt
- service.running:
- \- name: libvirtd
- \- require:
- \- pkg: libvirt
- \- network: br0
- \- libvirt: libvirt
- \- watch:
- \- file: libvirt
-
-libvirt\-python:
- pkg.installed: []
-
-libguestfs:
- pkg.installed:
- \- pkgs:
- \- libguestfs
- \- libguestfs\-tools
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.SS Hypervisor Network Setup
-.sp
-The hypervisors will need to be running a network bridge to serve up network
-devices for virtual machines, this formula will set up a standard bridge on
-a hypervisor connecting the bridge to eth0:
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-eth0:
- network.managed:
- \- enabled: True
- \- type: eth
- \- bridge: br0
-
-br0:
- network.managed:
- \- enabled: True
- \- type: bridge
- \- proto: dhcp
- \- require:
- \- network: eth0
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.SS Virtual Machine Network Setup
-.sp
-Salt Virt comes with a system to model the network interfaces used by the
-deployed virtual machines; by default a single interface is created for the
-deployed virtual machine and is bridged to \fBbr0\fP\&. To get going with the
-default networking setup, ensure that the bridge interface named \fBbr0\fP exists
-on the hypervisor and is bridged to an active network device.
-.sp
-\fBNOTE:\fP
-.INDENT 0.0
-.INDENT 3.5
-To use more advanced networking in Salt Virt, read the \fISalt Virt
-Networking\fP document:
-.sp
-Salt Virt Networking
-.UNINDENT
-.UNINDENT
-.SS Libvirt State
-.sp
-One of the challenges of deploying a libvirt based cloud is the distribution
-of libvirt certificates. These certificates allow for virtual machine
-migration. Salt comes with a system used to auto deploy these certificates.
-Salt manages the signing authority key and generates keys for libvirt clients
-on the master, signs them with the certificate authority and uses pillar to
-distribute them. This is managed via the \fBlibvirt\fP state. Simply execute this
-formula on the minion to ensure that the certificate is in place and up to
-date:
-.sp
-\fBNOTE:\fP
-.INDENT 0.0
-.INDENT 3.5
-The above formula includes the calls needed to set up libvirt keys.
-.UNINDENT
-.UNINDENT
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-libvirt_keys:
- virt.keys
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.SS Getting Virtual Machine Images Ready
-.sp
-Salt Virt, requires that virtual machine images be provided as these are not
-generated on the fly. Generating these virtual machine images differs greatly
-based on the underlying platform.
-.sp
-Virtual machine images can be manually created using KVM and running through
-the installer, but this process is not recommended since it is very manual and
-prone to errors.
-.sp
-Virtual Machine generation applications are available for many platforms:
-.INDENT 0.0
-.TP
-.B kiwi: (openSUSE, SLES, RHEL, CentOS)
-\fI\%https://suse.github.io/kiwi/\fP
-.TP
-.B vm\-builder:
-\fI\%https://wiki.debian.org/VMBuilder\fP
-.sp
-\fBSEE ALSO:\fP
-.INDENT 7.0
-.INDENT 3.5
-\fI\%vmbuilder\-formula\fP
-.UNINDENT
-.UNINDENT
-.UNINDENT
-.sp
-Once virtual machine images are available, the easiest way to make them
-available to Salt Virt is to place them in the Salt file server. Just copy an
-image into \fB/srv/salt\fP and it can now be used by Salt Virt.
-.sp
-For purposes of this demo, the file name \fBcentos.img\fP will be used.
-.SS Existing Virtual Machine Images
-.sp
-Many existing Linux distributions distribute virtual machine images which
-can be used with Salt Virt. Please be advised that NONE OF THESE IMAGES ARE
-SUPPORTED BY SALTSTACK.
-.SS CentOS
-.sp
-These images have been prepared for OpenNebula but should work without issue with
-Salt Virt, only the raw qcow image file is needed:
-\fI\%http://wiki.centos.org/Cloud/OpenNebula\fP
-.SS Fedora Linux
-.sp
-Images for Fedora Linux can be found here:
-\fI\%http://fedoraproject.org/en/get\-fedora#clouds\fP
-.SS openSUSE
-.sp
-\fI\%http://download.opensuse.org/repositories/openSUSE:/Leap:/42.1:/Images/images\fP
-.sp
-(look for JeOS\-for\-kvm\-and\-xen variant)
-.SS SUSE
-.sp
-\fI\%https://www.suse.com/products/server/jeos\fP
-.SS Ubuntu Linux
-.sp
-Images for Ubuntu Linux can be found here:
-\fI\%http://cloud\-images.ubuntu.com/\fP
-.SS Using Salt Virt
-.sp
-With hypervisors set up and virtual machine images ready, Salt can start
-issuing cloud commands using the \fIvirt runner\fP\&.
-.sp
-Start by running a Salt Virt hypervisor info command:
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-salt\-run virt.host_info
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-This will query the running hypervisor(s) for stats and display useful
-information such as the number of cpus and amount of memory.
-.sp
-You can also list all VMs and their current states on all hypervisor
-nodes:
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-salt\-run virt.list
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-Now that hypervisors are available a virtual machine can be provisioned.
-The \fBvirt.init\fP routine will create a new virtual machine:
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-salt\-run virt.init centos1 2 512 salt://centos.img
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-The Salt Virt runner will now automatically select a hypervisor to deploy
-the new virtual machine on. Using \fBsalt://\fP assumes that the CentOS virtual
-machine image is located in the root of the file\-server on the master.
-When images are cloned (i.e. copied locatlly after retrieval from the file server)
-the destination directory on the hypervisor minion is determined by the \fBvirt.images\fP
-config option; by default this is \fB/srv/salt/salt\-images/\fP\&.
-.sp
-When a VM is initialized using \fBvirt.init\fP the image is copied to the hypervisor
-using \fBcp.cache_file\fP and will be mounted and seeded with a minion. Seeding includes
-setting pre\-authenticated keys on the new machine. A minion will only be installed if
-one can not be found on the image using the default arguments to \fBseed.apply\fP\&.
-.sp
-\fBNOTE:\fP
-.INDENT 0.0
-.INDENT 3.5
-The biggest bottleneck in starting VMs is when the Salt Minion needs to be
-installed. Making sure that the source VM images already have Salt
-installed will GREATLY speed up virtual machine deployment.
-.UNINDENT
-.UNINDENT
-.sp
-You can also deploy an image on a particular minion by directly calling the
-\fIvirt\fP execution module with an absolute image path. This can be quite handy for testing:
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-salt \(aqhypervisor*\(aq virt.init centos1 2 512 image=/var/lib/libvirt/images/centos.img
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-Now that the new VM has been prepared, it can be seen via the \fBvirt.query\fP
-command:
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-salt\-run virt.query
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-This command will return data about all of the hypervisors and respective
-virtual machines.
-.sp
-Now that the new VM is booted it should have contacted the Salt Master, a
-\fBtest.ping\fP will reveal if the new VM is running.
-.SS QEMU copy on write support
-.sp
-For fast image cloning you can use the \fI\%qcow\fP disk image format.
-Pass the \fBenable_qcow\fP flag and a \fI\&.qcow2\fP image path to \fIvirt.init\fP:
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-salt \(aqhypervisor*\(aq virt.init centos1 2 512 image=/var/lib/libvirt/images/centos.qcow2 enable_qcow=True start=False
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-\fBNOTE:\fP
-.INDENT 0.0
-.INDENT 3.5
-Beware that attempting to boot a qcow image too quickly after cloning
-can result in a race condition where libvirt may try to boot the machine
-before image seeding has completed. For that reason it is recommended to
-also pass \fBstart=False\fP to \fBvirt.init\fP\&.
-.sp
-Also know that you \fBmust not\fP modify the original base image without
-first making a copy and then \fIrebasing\fP all overlay images onto it.
-See the \fBqemu\-img rebase\fP \fI\%usage docs\fP\&.
-.UNINDENT
-.UNINDENT
-.SS Migrating Virtual Machines
-.sp
-Salt Virt comes with full support for virtual machine migration, and using
-the libvirt state in the above formula makes migration possible.
-.sp
-A few things need to be available to support migration. Many operating systems
-turn on firewalls when originally set up, the firewall needs to be opened up
-to allow for libvirt and kvm to cross communicate and execution migration
-routines. On Red Hat based hypervisors in particular port 16514 needs to be
-opened on hypervisors:
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-iptables \-A INPUT \-m state \-\-state NEW \-m tcp \-p tcp \-\-dport 16514 \-j ACCEPT
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-\fBNOTE:\fP
-.INDENT 0.0
-.INDENT 3.5
-More in\-depth information regarding distribution specific firewall settings can read in:
-.sp
-Opening the Firewall up for Salt
-.UNINDENT
-.UNINDENT
-.sp
-Salt also needs the \fBvirt.tunnel\fP option to be turned on.
-This flag tells Salt to run migrations securely via the libvirt TLS tunnel and to
-use port 16514. Without \fBvirt.tunnel\fP libvirt tries to bind to random ports when
-running migrations.
-.sp
-To turn on \fBvirt.tunnel\fP simple apply it to the master config file:
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-virt.tunnel: True
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-Once the master config has been updated, restart the master and send out a call
-to the minions to refresh the pillar to pick up on the change:
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-salt \e* saltutil.refresh_modules
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-Now, migration routines can be run! To migrate a VM, simply run the Salt Virt
-migrate routine:
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-salt\-run virt.migrate centos
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.SS VNC Consoles
-.sp
-Although not enabled by default, Salt Virt can also set up VNC consoles allowing for remote visual
-consoles to be opened up. When creating a new VM using \fBvirt.init\fP pass the \fBenable_vnc=True\fP
-parameter to have a console configured for the new VM.
-.sp
-The information from a \fBvirt.query\fP routine will display the vnc console port for the specific vms:
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-centos
- CPU: 2
- Memory: 524288
- State: running
- Graphics: vnc \- hyper6:5900
- Disk \- vda:
- Size: 2.0G
- File: /srv/salt\-images/ubuntu2/system.qcow2
- File Format: qcow2
- Nic \- ac:de:48:98:08:77:
- Source: br0
- Type: bridge
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-The line \fIGraphics: vnc \- hyper6:5900\fP holds the key. First the port named,
-in this case 5900, will need to be available in the hypervisor\(aqs firewall.
-Once the port is open, then the console can be easily opened via vncviewer:
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-vncviewer hyper6:5900
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-By default there is no VNC security set up on these ports, which suggests that
-keeping them firewalled and mandating that SSH tunnels be used to access these
-VNC interfaces. Keep in mind that activity on a VNC interface that is accessed
-can be viewed by any other user that accesses that same VNC interface, and any other
-user logging in can also operate with the logged in user on the virtual
-machine.
-.SS Conclusion
-.sp
-Now with Salt Virt running, new hypervisors can be seamlessly added just by
-running the above states on new bare metal machines, and these machines will be
-instantly available to Salt Virt.
.SH COMMAND LINE REFERENCE
.SS salt\-call
.SS \fBsalt\-call\fP
@@ -69545,9 +76424,9 @@ output. Set to True or False. Default: none.
.UNINDENT
.SS See also
.sp
-\fBsalt(1)\fP
-\fBsalt\-master(1)\fP
-\fBsalt\-minion(1)\fP
+\fIsalt(1)\fP
+\fIsalt\-master(1)\fP
+\fIsalt\-minion(1)\fP
.SS salt
.SS \fBsalt\fP
.SS Synopsis
@@ -69615,16 +76494,6 @@ the started execution and complete.
.UNINDENT
.INDENT 0.0
.TP
-.B \-\-state\-output=STATE_OUTPUT
-New in version 0.17.
-
-.sp
-Override the configured \fBstate_output\fP value for minion output. One of
-\fBfull\fP, \fBterse\fP, \fBmixed\fP, \fBchanges\fP or \fBfilter\fP\&. Default:
-\fBfull\fP\&.
-.UNINDENT
-.INDENT 0.0
-.TP
.B \-\-subset=SUBSET
Execute the routine on a random subset of the targeted minions. The
minions will be verified that they have the named function before
@@ -69864,9 +76733,9 @@ output. Set to True or False. Default: none.
.UNINDENT
.SS See also
.sp
-\fBsalt(7)\fP
-\fBsalt\-master(1)\fP
-\fBsalt\-minion(1)\fP
+\fIsalt(7)\fP
+\fIsalt\-master(1)\fP
+\fIsalt\-minion(1)\fP
.SS salt\-cloud
.SS salt\-cp
.SS \fBsalt\-cp\fP
@@ -70041,9 +76910,9 @@ New in version 2016.3.7,2016.11.6,2017.7.0.
.UNINDENT
.SS See also
.sp
-\fBsalt(1)\fP
-\fBsalt\-master(1)\fP
-\fBsalt\-minion(1)\fP
+\fIsalt(1)\fP
+\fIsalt\-master(1)\fP
+\fIsalt\-minion(1)\fP
.SS salt\-extend
.SS \fBsalt\-extend\fP
.sp
@@ -70111,17 +76980,17 @@ Print debug messages to stdout
.UNINDENT
.SS See also
.sp
-\fBsalt\-api(1)\fP
-\fBsalt\-call(1)\fP
-\fBsalt\-cloud(1)\fP
-\fBsalt\-cp(1)\fP
-\fBsalt\-key(1)\fP
-\fBsalt\-main(1)\fP
-\fBsalt\-master(1)\fP
-\fBsalt\-minion(1)\fP
-\fBsalt\-run(1)\fP
-\fBsalt\-ssh(1)\fP
-\fBsalt\-syndic(1)\fP
+\fIsalt\-api(1)\fP
+\fIsalt\-call(1)\fP
+\fIsalt\-cloud(1)\fP
+\fIsalt\-cp(1)\fP
+\fIsalt\-key(1)\fP
+\fIsalt\-main(1)\fP
+\fIsalt\-master(1)\fP
+\fIsalt\-minion(1)\fP
+\fIsalt\-run(1)\fP
+\fIsalt\-ssh(1)\fP
+\fIsalt\-syndic(1)\fP
.SS salt\-key
.SS \fBsalt\-key\fP
.SS Synopsis
@@ -70434,9 +77303,9 @@ Auto\-create a signing key\-pair if it does not yet exist
.UNINDENT
.SS See also
.sp
-\fBsalt(7)\fP
-\fBsalt\-master(1)\fP
-\fBsalt\-minion(1)\fP
+\fIsalt(7)\fP
+\fIsalt\-master(1)\fP
+\fIsalt\-minion(1)\fP
.SS salt\-master
.SS \fBsalt\-master\fP
.sp
@@ -70517,9 +77386,9 @@ Logfile logging log level. One of \fBall\fP, \fBgarbage\fP, \fBtrace\fP,
.UNINDENT
.SS See also
.sp
-\fBsalt(1)\fP
-\fBsalt(7)\fP
-\fBsalt\-minion(1)\fP
+\fIsalt(1)\fP
+\fIsalt(7)\fP
+\fIsalt\-minion(1)\fP
.SS salt\-minion
.SS \fBsalt\-minion\fP
.sp
@@ -70601,9 +77470,9 @@ Logfile logging log level. One of \fBall\fP, \fBgarbage\fP, \fBtrace\fP,
.UNINDENT
.SS See also
.sp
-\fBsalt(1)\fP
-\fBsalt(7)\fP
-\fBsalt\-master(1)\fP
+\fIsalt(1)\fP
+\fIsalt(7)\fP
+\fIsalt\-master(1)\fP
.SS salt\-proxy
.SS \fBsalt\-proxy\fP
.sp
@@ -70692,10 +77561,10 @@ Logfile logging log level. One of \fBall\fP, \fBgarbage\fP, \fBtrace\fP,
.UNINDENT
.SS See also
.sp
-\fBsalt(1)\fP
-\fBsalt(7)\fP
-\fBsalt\-master(1)\fP
-\fBsalt\-minion(1)\fP
+\fIsalt(1)\fP
+\fIsalt(7)\fP
+\fIsalt\-master(1)\fP
+\fIsalt\-minion(1)\fP
.SS salt\-run
.SS \fBsalt\-run\fP
.sp
@@ -70782,9 +77651,9 @@ Logfile logging log level. One of \fBall\fP, \fBgarbage\fP, \fBtrace\fP,
.UNINDENT
.SS See also
.sp
-\fBsalt(1)\fP
-\fBsalt\-master(1)\fP
-\fBsalt\-minion(1)\fP
+\fIsalt(1)\fP
+\fIsalt\-master(1)\fP
+\fIsalt\-minion(1)\fP
.SS salt\-ssh
.SS \fBsalt\-ssh\fP
.SS Synopsis
@@ -71105,9 +77974,9 @@ output. Set to True or False. Default: none.
.UNINDENT
.SS See also
.sp
-\fBsalt(7)\fP
-\fBsalt\-master(1)\fP
-\fBsalt\-minion(1)\fP
+\fIsalt(7)\fP
+\fIsalt\-master(1)\fP
+\fIsalt\-minion(1)\fP
.SS salt\-syndic
.SS \fBsalt\-syndic\fP
.sp
@@ -71190,9 +78059,42 @@ Logfile logging log level. One of \fBall\fP, \fBgarbage\fP, \fBtrace\fP,
.UNINDENT
.SS See also
.sp
-\fBsalt(1)\fP
-\fBsalt\-master(1)\fP
-\fBsalt\-minion(1)\fP
+\fIsalt(1)\fP
+\fIsalt\-master(1)\fP
+\fIsalt\-minion(1)\fP
+.SS salt\-unity
+.SS \fBsalt\-unity\fP
+.sp
+A unified invocation wrapper around other Salt CLI scripts.
+.SS Synopsis
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+salt\-unity salt \(aq*\(aq test.ping
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.SS Description
+.sp
+This script takes an argument which is one of the other Salt CLI scripts and
+invokes that script.
+.SS Options
+.SS See also
+.sp
+\fIsalt\-api(1)\fP
+\fIsalt\-call(1)\fP
+\fIsalt\-cloud(1)\fP
+\fIsalt\-cp(1)\fP
+\fIsalt\-key(1)\fP
+\fIsalt\-main(1)\fP
+\fIsalt\-master(1)\fP
+\fIsalt\-minion(1)\fP
+\fIsalt\-run(1)\fP
+\fIsalt\-ssh(1)\fP
+\fIsalt\-syndic(1)\fP
.SS salt\-api
.SS \fBsalt\-api\fP
.sp
@@ -71268,9 +78170,9 @@ Logfile logging log level. One of \fBall\fP, \fBgarbage\fP, \fBtrace\fP,
.UNINDENT
.SS See also
.sp
-\fBsalt\-api(7)\fP
-\fBsalt(7)\fP
-\fBsalt\-master(1)\fP
+\fIsalt\-api(7)\fP
+\fIsalt(7)\fP
+\fIsalt\-master(1)\fP
.SS spm
.SS \fBspm\fP
.sp
@@ -71375,9 +78277,35 @@ in that directory which describes them.
.UNINDENT
.SS See also
.sp
-\fBsalt(1)\fP
-\fBsalt\-master(1)\fP
-\fBsalt\-minion(1)\fP
+\fIsalt(1)\fP
+\fIsalt\-master(1)\fP
+\fIsalt\-minion(1)\fP
+.SH PILLARS
+.sp
+Salt includes a number of built\-in external pillars, listed at
+all\-salt.pillars\&.
+.sp
+The below links contain documentation for the configuration options
+.INDENT 0.0
+.IP \(bu 2
+master\-side configuration
+.IP \(bu 2
+minion\-side configuration
+.UNINDENT
+.sp
+Note that some of same the configuration options from the master are present in
+the minion configuration file, these are used in masterless mode.
+.sp
+The source for the built\-in Salt pillars can be found here:
+\fI\%https://github.com/saltstack/salt/blob/develop/salt/pillar\fP
+.SH MASTER TOPS
+.sp
+Salt includes a number of built\-in subsystems to generate top file data, they
+are listed at
+all\-salt.tops\&.
+.sp
+The source for the built\-in Salt master tops can be found here:
+\fI\%https://github.com/saltstack/salt/blob/develop/salt/tops\fP
.SH SALT MODULE REFERENCE
.sp
This section contains a list of the Python modules that are used to extend the various subsystems within Salt.
@@ -71852,6 +78780,11 @@ Wrapper class for pam_response structure
.UNINDENT
.INDENT 0.0
.TP
+.B salt.auth.pam.__virtual__()
+Only load on Linux systems
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.auth.pam.auth(username, password, **kwargs)
Authenticate via pam
.UNINDENT
@@ -71897,6 +78830,11 @@ pyOpenSSL module
.UNINDENT
.INDENT 0.0
.TP
+.B salt.auth.pki.__virtual__()
+Requires newer pycrypto and pyOpenSSL
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.auth.pki.auth(username, password, **kwargs)
Returns True if the given user cert (password is the cert contents)
was issued by the CA and if cert\(aqs Common Name is equal to username.
@@ -72212,7 +79150,7 @@ _
T{
\fBsensehat\fP
T} T{
-Beacon to monitor temperature, humidity and pressure using the SenseHat of a Raspberry Pi.
+Monitor temperature, humidity and pressure using the SenseHat of a Raspberry Pi
T}
_
T{
@@ -72258,6 +79196,11 @@ Beacon to emit adb device state changes for Android devices
.sp
New in version 2016.3.0.
+.INDENT 0.0
+.TP
+.B salt.beacons.adb.__validate__(config)
+Validate the beacon configuration
+.UNINDENT
.INDENT 0.0
.TP
.B salt.beacons.adb.beacon(config)
@@ -72299,65 +79242,60 @@ dbus\-python
.UNINDENT
.INDENT 0.0
.TP
+.B salt.beacons.avahi_announce.__validate__(config)
+Validate the beacon configuration
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.beacons.avahi_announce.beacon(config)
Broadcast values via zeroconf
.sp
If the announced values are static, it is advised to set run_once: True
(do not poll) on the beacon configuration.
+.sp
+The following are required configuration settings:
.INDENT 7.0
-.TP
-.B The following are required configuration settings:
-\(aqservicetype\(aq: The service type to announce.
-\(aqport\(aq: The port of the service to announce.
-\(aqtxt\(aq: The TXT record of the service being announced as a dict.
-.INDENT 7.0
-.INDENT 3.5
-.INDENT 0.0
-.TP
-.B Grains can be used to define TXT values using the syntax:
-grains.
-.TP
-.B or:
-grains.[i]
+.IP \(bu 2
+\fBservicetype\fP \- The service type to announce
+.IP \(bu 2
+\fBport\fP \- The port of the service to announce
+.IP \(bu 2
+\fBtxt\fP \- The TXT record of the service being announced as a dict. Grains
+can be used to define TXT values using one of following two formats:
+.INDENT 2.0
+.IP \(bu 2
+\fBgrains.\fP
+.IP \(bu 2
+\fBgrains.[i]\fP where i is an integer representing the
+index of the grain to use. If the grain is not a list, the index is
+ignored.
+.UNINDENT
.UNINDENT
.sp
-where i is an integer representing the index of the grain to
-use. If the grain is not a list, the index is ignored.
-.UNINDENT
-.UNINDENT
-.TP
-.B The following are optional configuration settings:
+The following are optional configuration settings:
.INDENT 7.0
-.TP
-.B \(aqservicename\(aq: Set the name of the service. Will use the hostname from
-__grains__[\(aqhost\(aq] if not set.
-.TP
-.B \(aqreset_on_change\(aq: If true and there is a change in TXT records
-detected, it will stop announcing the service and
-then restart announcing the service. This
-interruption in service announcement may be
-desirable if the client relies on changes in the
-browse records to update its cache of the TXT
-records.
-Defaults to False.
-.TP
-.B \(aqreset_wait\(aq: The number of seconds to wait after announcement stops
-announcing and before it restarts announcing in the
-case where there is a change in TXT records detected
-and \(aqreset_on_change\(aq is True.
-Defaults to 0.
-.TP
-.B \(aqcopy_grains\(aq: If set to True, it will copy the grains passed into
-the beacon when it backs them up to check for changes
-on the next iteration. Normally, instead of copy, it
-would use straight value assignment. This will allow
-detection of changes to grains where the grains are
-modified in\-place instead of completely replaced.
-In\-place grains changes are not currently done in the
-main Salt code but may be done due to a custom
-plug\-in.
-Defaults to False.
-.UNINDENT
+.IP \(bu 2
+\fBservicename\fP \- Set the name of the service. Will use the hostname from
+the minion\(aqs \fBhost\fP grain if this value is not set.
+.IP \(bu 2
+\fBreset_on_change\fP \- If \fBTrue\fP and there is a change in TXT records
+detected, it will stop announcing the service and then restart announcing
+the service. This interruption in service announcement may be desirable
+if the client relies on changes in the browse records to update its cache
+of TXT records. Defaults to \fBFalse\fP\&.
+.IP \(bu 2
+\fBreset_wait\fP \- The number of seconds to wait after announcement stops
+announcing and before it restarts announcing in the case where there is a
+change in TXT records detected and \fBreset_on_change\fP is \fBTrue\fP\&.
+Defaults to \fB0\fP\&.
+.IP \(bu 2
+\fBcopy_grains\fP \- If \fBTrue\fP, Salt will copy the grains passed into the
+beacon when it backs them up to check for changes on the next iteration.
+Normally, instead of copy, it would use straight value assignment. This
+will allow detection of changes to grains where the grains are modified
+in\-place instead of completely replaced. In\-place grains changes are not
+currently done in the main Salt code but may be done due to a custom
+plug\-in. Defaults to \fBFalse\fP\&.
.UNINDENT
.sp
Example Config
@@ -72385,65 +79323,60 @@ beacons:
Beacon to announce via Bonjour (zeroconf)
.INDENT 0.0
.TP
+.B salt.beacons.bonjour_announce.__validate__(config)
+Validate the beacon configuration
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.beacons.bonjour_announce.beacon(config)
Broadcast values via zeroconf
.sp
If the announced values are static, it is advised to set run_once: True
(do not poll) on the beacon configuration.
+.sp
+The following are required configuration settings:
.INDENT 7.0
-.TP
-.B The following are required configuration settings:
-\(aqservicetype\(aq: The service type to announce.
-\(aqport\(aq: The port of the service to announce.
-\(aqtxt\(aq: The TXT record of the service being announced as a dict.
-.INDENT 7.0
-.INDENT 3.5
-.INDENT 0.0
-.TP
-.B Grains can be used to define TXT values using the syntax:
-grains.
-.TP
-.B or:
-grains.[i]
+.IP \(bu 2
+\fBservicetype\fP \- The service type to announce
+.IP \(bu 2
+\fBport\fP \- The port of the service to announce
+.IP \(bu 2
+\fBtxt\fP \- The TXT record of the service being announced as a dict. Grains
+can be used to define TXT values using one of following two formats:
+.INDENT 2.0
+.IP \(bu 2
+\fBgrains.\fP
+.IP \(bu 2
+\fBgrains.[i]\fP where i is an integer representing the
+index of the grain to use. If the grain is not a list, the index is
+ignored.
+.UNINDENT
.UNINDENT
.sp
-where i is an integer representing the index of the grain to
-use. If the grain is not a list, the index is ignored.
-.UNINDENT
-.UNINDENT
-.TP
-.B The following are optional configuration settings:
+The following are optional configuration settings:
.INDENT 7.0
-.TP
-.B \(aqservicename\(aq: Set the name of the service. Will use the hostname from
-__grains__[\(aqhost\(aq] if not set.
-.TP
-.B \(aqreset_on_change\(aq: If true and there is a change in TXT records
-detected, it will stop announcing the service and
-then restart announcing the service. This
-interruption in service announcement may be
-desirable if the client relies on changes in the
-browse records to update its cache of the TXT
-records.
-Defaults to False.
-.TP
-.B \(aqreset_wait\(aq: The number of seconds to wait after announcement stops
-announcing and before it restarts announcing in the
-case where there is a change in TXT records detected
-and \(aqreset_on_change\(aq is True.
-Defaults to 0.
-.TP
-.B \(aqcopy_grains\(aq: If set to True, it will copy the grains passed into
-the beacon when it backs them up to check for changes
-on the next iteration. Normally, instead of copy, it
-would use straight value assignment. This will allow
-detection of changes to grains where the grains are
-modified in\-place instead of completely replaced.
-In\-place grains changes are not currently done in the
-main Salt code but may be done due to a custom
-plug\-in.
-Defaults to False.
-.UNINDENT
+.IP \(bu 2
+\fBservicename\fP \- Set the name of the service. Will use the hostname from
+the minion\(aqs \fBhost\fP grain if this value is not set.
+.IP \(bu 2
+\fBreset_on_change\fP \- If \fBTrue\fP and there is a change in TXT records
+detected, it will stop announcing the service and then restart announcing
+the service. This interruption in service announcement may be desirable
+if the client relies on changes in the browse records to update its cache
+of TXT records. Defaults to \fBFalse\fP\&.
+.IP \(bu 2
+\fBreset_wait\fP \- The number of seconds to wait after announcement stops
+announcing and before it restarts announcing in the case where there is a
+change in TXT records detected and \fBreset_on_change\fP is \fBTrue\fP\&.
+Defaults to \fB0\fP\&.
+.IP \(bu 2
+\fBcopy_grains\fP \- If \fBTrue\fP, Salt will copy the grains passed into the
+beacon when it backs them up to check for changes on the next iteration.
+Normally, instead of copy, it would use straight value assignment. This
+will allow detection of changes to grains where the grains are modified
+in\-place instead of completely replaced. In\-place grains changes are not
+currently done in the main Salt code but may be done due to a custom
+plug\-in. Defaults to \fBFalse\fP\&.
.UNINDENT
.sp
Example Config
@@ -72482,6 +79415,11 @@ beacons:
.UNINDENT
.INDENT 0.0
.TP
+.B salt.beacons.btmp.__validate__(config)
+Validate the beacon configuration
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.beacons.btmp.beacon(config)
Read the last btmp file and return information on the failed logins
.INDENT 7.0
@@ -72509,6 +79447,11 @@ python\-psutil
.UNINDENT
.INDENT 0.0
.TP
+.B salt.beacons.diskusage.__validate__(config)
+Validate the beacon configuration
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.beacons.diskusage.beacon(config)
Monitor the disk usage of the minion
.sp
@@ -72572,6 +79515,11 @@ Beacon to emit when a display is available to a linux machine
.sp
New in version 2016.3.0.
+.INDENT 0.0
+.TP
+.B salt.beacons.glxinfo.__validate__(config)
+Validate the beacon configuration
+.UNINDENT
.INDENT 0.0
.TP
.B salt.beacons.glxinfo.beacon(config)
@@ -72599,6 +79547,16 @@ Fire an event when over a specified threshold.
.sp
New in version 2016.11.0.
+.INDENT 0.0
+.TP
+.B salt.beacons.haproxy.__validate__(config)
+Validate the beacon configuration
+.UNINDENT
+.INDENT 0.0
+.TP
+.B salt.beacons.haproxy.__virtual__()
+Only load the module if haproxyctl module is installed
+.UNINDENT
.INDENT 0.0
.TP
.B salt.beacons.haproxy.beacon(config)
@@ -72646,6 +79604,11 @@ Currently this excludes FreeBSD, macOS, and Windows.
.UNINDENT
.INDENT 0.0
.TP
+.B salt.beacons.inotify.__validate__(config)
+Validate the beacon configuration
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.beacons.inotify.beacon(config)
Watch the configured files
.sp
@@ -72743,6 +79706,11 @@ being at the Notifier level in pyinotify.
A simple beacon to watch journald for specific entries
.INDENT 0.0
.TP
+.B salt.beacons.journald.__validate__(config)
+Validate the beacon configuration
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.beacons.journald.beacon(config)
The journald beacon allows for the systemd journal to be parsed and linked
objects to be turned into events.
@@ -72768,6 +79736,11 @@ beacons:
Beacon to emit system load averages
.INDENT 0.0
.TP
+.B salt.beacons.load.__validate__(config)
+Validate the beacon configuration
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.beacons.load.beacon(config)
Emit the load averages of this host.
.sp
@@ -72813,6 +79786,11 @@ Beacon to fire events at specific log messages.
.sp
New in version 2017.7.0.
+.INDENT 0.0
+.TP
+.B salt.beacons.log.__validate__(config)
+Validate the beacon configuration
+.UNINDENT
.INDENT 0.0
.TP
.B salt.beacons.log.beacon(config)
@@ -72845,6 +79823,11 @@ python\-psutil
.UNINDENT
.INDENT 0.0
.TP
+.B salt.beacons.memusage.__validate__(config)
+Validate the beacon configuration
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.beacons.memusage.beacon(config)
Monitor the memory usage of the minion
.sp
@@ -72868,6 +79851,11 @@ Beacon to monitor statistics from ethernet adapters
.sp
New in version 2015.5.0.
+.INDENT 0.0
+.TP
+.B salt.beacons.network_info.__validate__(config)
+Validate the beacon configuration
+.UNINDENT
.INDENT 0.0
.TP
.B salt.beacons.network_info.beacon(config)
@@ -72938,6 +79926,11 @@ Helper class that implements a hash function for a dictionary
.UNINDENT
.INDENT 0.0
.TP
+.B salt.beacons.network_settings.__validate__(config)
+Validate the beacon configuration
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.beacons.network_settings.beacon(config)
Watch for changes on network settings
.sp
@@ -72995,6 +79988,16 @@ Watch for pkgs that have upgrades, then fire an event.
.sp
New in version 2016.3.0.
+.INDENT 0.0
+.TP
+.B salt.beacons.pkg.__validate__(config)
+Validate the beacon configuration
+.UNINDENT
+.INDENT 0.0
+.TP
+.B salt.beacons.pkg.__virtual__()
+Only load if strace is installed
+.UNINDENT
.INDENT 0.0
.TP
.B salt.beacons.pkg.beacon(config)
@@ -73033,6 +80036,17 @@ beacons:
.UNINDENT
.INDENT 0.0
.TP
+.B salt.beacons.proxy_example.__validate__(config)
+Validate the beacon configuration
+.UNINDENT
+.INDENT 0.0
+.TP
+.B salt.beacons.proxy_example.__virtual__()
+Trivially let the beacon load for the test example.
+For a production beacon we should probably have some expression here.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.beacons.proxy_example.beacon(config)
Called several times each second
\fI\%https://docs.saltstack.com/en/latest/topics/beacons/#the\-beacon\-function\fP
@@ -73054,6 +80068,11 @@ beacons:
Send events covering service status
.INDENT 0.0
.TP
+.B salt.beacons.ps.__validate__(config)
+Validate the beacon configuration
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.beacons.ps.beacon(config)
Scan for processes and fire events
.sp
@@ -73101,9 +80120,7 @@ beacons:
.UNINDENT
.UNINDENT
.SS salt.beacons.sensehat module
-.sp
-Beacon to monitor temperature, humidity and pressure using the SenseHat
-of a Raspberry Pi.
+.SS Monitor temperature, humidity and pressure using the SenseHat of a Raspberry Pi
.sp
New in version 2017.7.0.
@@ -73120,6 +80137,11 @@ sense_hat Python module
.UNINDENT
.INDENT 0.0
.TP
+.B salt.beacons.sensehat.__validate__(config)
+Validate the beacon configuration
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.beacons.sensehat.beacon(config)
Monitor the temperature, humidity and pressure using the SenseHat sensors.
.sp
@@ -73153,6 +80175,11 @@ beacons:
Send events covering service status
.INDENT 0.0
.TP
+.B salt.beacons.service.__validate__(config)
+Validate the beacon configuration
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.beacons.service.beacon(config)
Scan for the configured services and fire events
.sp
@@ -73223,6 +80250,16 @@ beacons:
Watch the shell commands being executed actively. This beacon requires strace.
.INDENT 0.0
.TP
+.B salt.beacons.sh.__validate__(config)
+Validate the beacon configuration
+.UNINDENT
+.INDENT 0.0
+.TP
+.B salt.beacons.sh.__virtual__()
+Only load if strace is installed
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.beacons.sh.beacon(config)
Scan the shell execve routines. This beacon will convert all login shells
.INDENT 7.0
@@ -73379,6 +80416,11 @@ to check the minion log for errors after configuring this beacon.
.UNINDENT
.INDENT 0.0
.TP
+.B salt.beacons.status.__validate__(config)
+Validate the the config is a dict
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.beacons.status.beacon(config)
Return status for requested information
.UNINDENT
@@ -73387,6 +80429,11 @@ Return status for requested information
Beacon to emit Telegram messages
.INDENT 0.0
.TP
+.B salt.beacons.telegram_bot_msg.__validate__(config)
+Validate the beacon configuration
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.beacons.telegram_bot_msg.beacon(config)
Emit a dict with a key "msgs" whose value is a list of messages
sent to the configured bot by one of the allowed usernames.
@@ -73411,6 +80458,11 @@ beacons:
Beacon to emit Twilio text messages
.INDENT 0.0
.TP
+.B salt.beacons.twilio_txt_msg.__validate__(config)
+Validate the beacon configuration
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.beacons.twilio_txt_msg.beacon(config)
Emit a dict name "texts" whose value is a list
of texts.
@@ -73446,6 +80498,11 @@ beacons:
.UNINDENT
.INDENT 0.0
.TP
+.B salt.beacons.wtmp.__validate__(config)
+Validate the beacon configuration
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.beacons.wtmp.beacon(config)
Read the last wtmp file and return information on the logins
.INDENT 7.0
@@ -73582,6 +80639,11 @@ cache: consul
.UNINDENT
.INDENT 0.0
.TP
+.B salt.cache.consul.__virtual__()
+Confirm this python\-consul package is installed
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.cache.consul.contains(bank, key)
Checks if the specified bank contains the specified key.
.UNINDENT
@@ -73613,25 +80675,25 @@ Redis plugin for the Salt caching subsystem.
New in version 2017.7.0.
.sp
-As Redis provides a simple mechanism for very fast key\-value store,
-in order to privde the necessary features for the Salt
-caching subsystem, the following conventions are used:
+As Redis provides a simple mechanism for very fast key\-value store, in order to
+privde the necessary features for the Salt caching subsystem, the following
+conventions are used:
.INDENT 0.0
.IP \(bu 2
-a Redis key consists of the bank name and the cache key separated by \fB/\fP, e.g.:
-.UNINDENT
-.sp
+A Redis key consists of the bank name and the cache key separated by \fB/\fP, e.g.:
\fB$KEY_minions/alpha/stuff\fP where \fBminions/alpha\fP is the bank name
and \fBstuff\fP is the key name.
-\- as the caching subsystem is organised as a tree, we need to store the
-caching path and identify the bank and its offspring.
-At the same time, Redis is linear
-and we need to avoid doing \fBkeys \fP which is very inefficient
-as it goes through all the keys on the remote Redis server.
-Instead, each bank hierarchy has a Redis SET associated
-which stores the list of sub\-banks. By default, these keys begin with \fB$BANK_\fP\&.
-\- in addition, each key name is stored in a separate SET
-of all the keys within a bank. By default, these SETs begin with \fB$BANKEYS_\fP\&.
+.IP \(bu 2
+As the caching subsystem is organised as a tree, we need to store the caching
+path and identify the bank and its offspring. At the same time, Redis is
+linear and we need to avoid doing \fBkeys \fP which is very
+inefficient as it goes through all the keys on the remote Redis server.
+Instead, each bank hierarchy has a Redis SET associated which stores the list
+of sub\-banks. By default, these keys begin with \fB$BANK_\fP\&.
+.IP \(bu 2
+In addition, each key name is stored in a separate SET of all the keys within
+a bank. By default, these SETs begin with \fB$BANKEYS_\fP\&.
+.UNINDENT
.sp
For example, to store the key \fBmy\-key\fP under the bank \fBroot\-bank/sub\-bank/leaf\-bank\fP,
the following hierarchy will be built:
@@ -73705,6 +80767,28 @@ Redis connection password.
.sp
Configuration Example:
.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+cache.redis.host: localhost
+cache.redis.port: 6379
+cache.redis.db: \(aq0\(aq
+cache.redis.password: my pass
+cache.redis.bank_prefix: #BANK
+cache.redis.bank_keys_prefix: #BANKEYS
+cache.redis.key_prefix: #KEY
+cache.redis.separator: \(aq@\(aq
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.INDENT 0.0
+.TP
+.B salt.cache.redis_cache.__virtual__()
+The redis library must be installed for this module to work.
+.UNINDENT
+.INDENT 0.0
.TP
.B salt.cache.redis_cache.contains(bank, key)
Checks if the specified bank contains the specified key.
@@ -73952,6 +81036,11 @@ requests
.UNINDENT
.INDENT 0.0
.TP
+.B salt.cloud.clouds.aliyun.__virtual__()
+Check for aliyun configurations
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.cloud.clouds.aliyun.avail_images(kwargs=None, call=None)
Return a list of the images that are on the provider
.UNINDENT
@@ -74238,6 +81327,11 @@ Or my\-azure\-config with service principal:
.UNINDENT
.INDENT 0.0
.TP
+.B salt.cloud.clouds.azurearm.__virtual__()
+Check for Azure configurations.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.cloud.clouds.azurearm.avail_images(conn=None, call=None)
List available images for Azure
.UNINDENT
@@ -74459,6 +81553,11 @@ my\-cloudstack\-cloud\-config:
.UNINDENT
.INDENT 0.0
.TP
+.B salt.cloud.clouds.cloudstack.__virtual__()
+Set up the libcloud functions and check for CloudStack configurations.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.cloud.clouds.cloudstack.avail_images(conn=None, call=None)
Return a dict of all available VM images on the cloud provider with
relevant data
@@ -74642,6 +81741,11 @@ requests
.UNINDENT
.INDENT 0.0
.TP
+.B salt.cloud.clouds.digital_ocean.__virtual__()
+Check for DigitalOcean configurations
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.cloud.clouds.digital_ocean.assign_floating_ip(kwargs=None, call=None)
Assign a floating IP
.sp
@@ -75022,6 +82126,11 @@ libcloud >= 1.2.1
.UNINDENT
.INDENT 0.0
.TP
+.B salt.cloud.clouds.dimensiondata.__virtual__()
+Set up the libcloud functions and check for dimensiondata configurations.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.cloud.clouds.dimensiondata.avail_images(conn=None, call=None)
Return a dict of all available VM images on the cloud provider with
relevant data
@@ -75262,6 +82371,11 @@ requests
.UNINDENT
.INDENT 0.0
.TP
+.B salt.cloud.clouds.ec2.__virtual__()
+Set up the libcloud functions and check for EC2 configurations
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.cloud.clouds.ec2.attach_volume(name=None, kwargs=None, instance_id=None, call=None)
Attach a volume to an instance
.UNINDENT
@@ -76117,6 +83231,11 @@ libcloud >= 1.0.0
.UNINDENT
.INDENT 0.0
.TP
+.B salt.cloud.clouds.gce.__virtual__()
+Set up the libcloud functions and check for GCE configurations.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.cloud.clouds.gce.attach_disk(name=None, kwargs=None, call=None)
Attach an existing disk to an existing instance.
.sp
@@ -76864,6 +83983,11 @@ argument should not be used on maps referencing GoGrid instances.
.UNINDENT
.INDENT 0.0
.TP
+.B salt.cloud.clouds.gogrid.__virtual__()
+Check for GoGrid configs
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.cloud.clouds.gogrid.avail_images()
Available images
.UNINDENT
@@ -77145,6 +84269,11 @@ PyCrypto
.UNINDENT
.INDENT 0.0
.TP
+.B salt.cloud.clouds.joyent.__virtual__()
+Check for Joyent configs
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.cloud.clouds.joyent.avail_images(call=None)
Get list of available images
.sp
@@ -77558,6 +84687,11 @@ linode\-profile:
.UNINDENT
.INDENT 0.0
.TP
+.B salt.cloud.clouds.linode.__virtual__()
+Check for Linode configs.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.cloud.clouds.linode.avail_images(call=None)
Return available Linode images.
.sp
@@ -78234,6 +85368,11 @@ New in version 2014.7.0.
Please read core config documentation\&.
.INDENT 0.0
.TP
+.B salt.cloud.clouds.lxc.__virtual__()
+Needs no special configuration
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.cloud.clouds.lxc.create(vm_, call=None)
Create an lxc Container.
This function is idempotent and will try to either provision
@@ -78318,6 +85457,11 @@ my\-azure\-config:
.UNINDENT
.INDENT 0.0
.TP
+.B salt.cloud.clouds.msazure.__virtual__()
+Check for Azure configurations.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.cloud.clouds.msazure.add_input_endpoint(kwargs=None, conn=None, call=None)
New in version 2015.8.0.
@@ -80417,6 +87561,11 @@ Note: For rackconnect v3, rackconnectv3 needs to be specified with the
rackconnect v3 cloud network as its variable.
.INDENT 0.0
.TP
+.B salt.cloud.clouds.nova.__virtual__()
+Check for Nova configurations
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.cloud.clouds.nova.attach_volume(name, server_name, device=\(aq/dev/xvdb\(aq, **kwargs)
Attach block volume
.UNINDENT
@@ -80734,6 +87883,11 @@ salt\-cloud \-f secgroup_allocate opennebula \e
.UNINDENT
.INDENT 0.0
.TP
+.B salt.cloud.clouds.opennebula.__virtual__()
+Check for OpenNebula configs.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.cloud.clouds.opennebula.avail_images(call=None)
Return available OpenNebula images.
.sp
@@ -80786,11 +87940,7 @@ Create a single VM from a data dict.
The dictionary use to create a VM.
.UNINDENT
.sp
-Optional
-.nf
-vm_
-.fi
- dict options for overwriting template:
+Optional vm_ dict options for overwriting template:
.INDENT 7.0
.TP
.B region_id
@@ -83213,6 +90363,11 @@ use the same ip address.
.UNINDENT
.INDENT 0.0
.TP
+.B salt.cloud.clouds.openstack.__virtual__()
+Set up the libcloud functions and check for OPENSTACK configurations
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.cloud.clouds.openstack.avail_images(conn=None, call=None)
Return a dict of all available VM images on the cloud provider with
relevant data
@@ -83362,6 +90517,11 @@ my\-parallels\-config:
.UNINDENT
.INDENT 0.0
.TP
+.B salt.cloud.clouds.parallels.__virtual__()
+Check for PARALLELS configurations
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.cloud.clouds.parallels.avail_images(call=None)
Return a list of the images that are on the provider
.UNINDENT
@@ -83593,6 +90753,11 @@ my\-profitbricks\-profile:
.UNINDENT
.INDENT 0.0
.TP
+.B salt.cloud.clouds.profitbricks.__virtual__()
+Check for ProfitBricks configurations.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.cloud.clouds.profitbricks.avail_images(call=None)
Return a list of the images that are on the provider
.UNINDENT
@@ -83883,6 +91048,11 @@ IPy >= 0.81
.UNINDENT
.INDENT 0.0
.TP
+.B salt.cloud.clouds.proxmox.__virtual__()
+Check for PROXMOX configurations
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.cloud.clouds.proxmox.avail_images(call=None, location=\(aqlocal\(aq)
Return a list of the images that are on the provider
.sp
@@ -84148,6 +91318,11 @@ you are actively developing code in this module, you should use the OpenStack
module instead.
.INDENT 0.0
.TP
+.B salt.cloud.clouds.pyrax.__virtual__()
+Check for Pyrax configurations
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.cloud.clouds.pyrax.get_configured_provider()
Return the first configured instance.
.UNINDENT
@@ -84197,6 +91372,11 @@ requests
.UNINDENT
.INDENT 0.0
.TP
+.B salt.cloud.clouds.qingcloud.__virtual__()
+Check for QingCloud configurations.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.cloud.clouds.qingcloud.avail_images(kwargs=None, call=None)
Return a list of the images that are on the provider.
.sp
@@ -84475,6 +91655,11 @@ files as described in the
Gettting Started with Saltify documentation.
.INDENT 0.0
.TP
+.B salt.cloud.clouds.saltify.__virtual__()
+Needs no special configuration
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.cloud.clouds.saltify.create(vm_)
Provision a single machine
.UNINDENT
@@ -84534,6 +91719,11 @@ requests
.UNINDENT
.INDENT 0.0
.TP
+.B salt.cloud.clouds.scaleway.__virtual__()
+Check for Scaleway configurations.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.cloud.clouds.scaleway.avail_images(call=None)
Return a list of the images that are on the provider.
.UNINDENT
@@ -84640,6 +91830,11 @@ softlayer
.UNINDENT
.INDENT 0.0
.TP
+.B salt.cloud.clouds.softlayer.__virtual__()
+Check for SoftLayer configurations.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.cloud.clouds.softlayer.avail_images(call=None)
Return a dict of all available VM images on the cloud provider.
.UNINDENT
@@ -84776,6 +91971,11 @@ softlayer
.UNINDENT
.INDENT 0.0
.TP
+.B salt.cloud.clouds.softlayer_hw.__virtual__()
+Check for SoftLayer configurations.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.cloud.clouds.softlayer_hw.avail_images(call=None)
Return a dict of all available VM images on the cloud provider.
.UNINDENT
@@ -84949,29 +92149,57 @@ as well as a set of configuration and environment variables
.UNINDENT
.INDENT 0.0
.TP
-.B salt.cloud.clouds.virtualbox.create(vm_info)
-Creates a virtual machine from the given VM information.
-This is what is used to request a virtual machine to be created by the
-cloud provider, wait for it to become available,
-and then (optionally) log in and install Salt on it.
+.B salt.cloud.clouds.virtualbox.__virtual__()
+This function determines whether or not
+to make this cloud module available upon execution.
+Most often, it uses get_configured_provider() to determine
.INDENT 7.0
-.TP
-.B Fires:
-"starting create" : This event is tagged salt/cloud//creating.
-The payload contains the names of the VM, profile and provider.
-.TP
-.B @param vm_info
-.INDENT 7.0
-.TP
-.B {
-name:
-profile:
-driver: :
-clonefrom:
-clonemode: (default: state, choices: state, child, all)
+.INDENT 3.5
+if the necessary configuration has been set up.
+.UNINDENT
.UNINDENT
.sp
+It may also check for necessary imports decide whether to load the module.
+In most cases, it will return a True or False value.
+If the name of the driver used does not match the filename,
+.INDENT 7.0
+.INDENT 3.5
+then that name should be returned instead of True.
+.UNINDENT
+.UNINDENT
+.sp
+@return True|False|str
+.UNINDENT
+.INDENT 0.0
+.TP
+.B salt.cloud.clouds.virtualbox.create(vm_info)
+Creates a virtual machine from the given VM information
+.sp
+This is what is used to request a virtual machine to be created by the
+cloud provider, wait for it to become available, and then (optionally) log
+in and install Salt on it.
+.sp
+Events fired:
+.sp
+This function fires the event \fBsalt/cloud/vm_name/creating\fP, with the
+payload containing the names of the VM, profile, and provider.
+.sp
+@param vm_info
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+{
+ name:
+ profile:
+ driver: :
+ clonefrom:
+ clonemode: (default: state, choices: state, child, all)
}
+.ft P
+.fi
+.UNINDENT
.UNINDENT
.sp
@type vm_info dict
@@ -85015,6 +92243,16 @@ No other fields should be returned in this function, and all of these fields sho
The private_ips and public_ips fields should always be of a list type, even if empty,
and the other fields should always be of a str type.
This function is normally called with the \-Q option:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+salt\-cloud \-Q
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
.sp
@param kwargs:
@type kwargs:
@@ -85032,6 +92270,16 @@ even if they would not normally be provided by the cloud provider.
.sp
This is because some functions both within Salt and 3rd party will break if an expected field is not present.
This function is normally called with the \-F option:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+salt\-cloud \-F
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
.sp
@param kwargs:
@type kwargs:
@@ -85221,6 +92469,11 @@ To test the connection for \fBmy\-vmware\-config\fP specified in the cloud
configuration, run \fI\%test_vcenter_connection()\fP
.INDENT 0.0
.TP
+.B salt.cloud.clouds.vmware.__virtual__()
+Check for VMware configuration and if required libs are available.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.cloud.clouds.vmware.add_host(kwargs=None, call=None)
Add a host system to the specified cluster or datacenter in this VMware environment
.sp
@@ -86504,6 +93757,11 @@ nyc\-4gb\-4cpu\-ubuntu\-14\-04:
.UNINDENT
.INDENT 0.0
.TP
+.B salt.cloud.clouds.vultrpy.__virtual__()
+Set up the Vultr functions and check for configurations
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.cloud.clouds.vultrpy.avail_images(conn=None)
Return available images
.UNINDENT
@@ -86670,6 +93928,11 @@ Send events from Docker events
:Depends: Docker API >= 1.22
.INDENT 0.0
.TP
+.B salt.engines.docker_events.__virtual__()
+Only load if docker libs are present
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.engines.docker_events.start(docker_url=\(aqunix://var/run/docker.sock\(aq, timeout=60, tag=\(aqsalt/engines/docker_events\(aq)
Scan for Docker events and fire events
.sp
@@ -86890,7 +94153,7 @@ engines:
.UNINDENT
.UNINDENT
.sp
-Available commands on irc are
+Available commands on irc are:
.INDENT 0.0
.TP
.B ping
@@ -86906,10 +94169,50 @@ list of everything else sent in the message
.sp
Example of usage
.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+08:33:57 @gtmanfred > !ping
+08:33:57 gtmanbot > gtmanfred: pong
+08:34:02 @gtmanfred > !echo ping
+08:34:02 gtmanbot > ping
+08:34:17 @gtmanfred > !event test/tag/ircbot irc is usefull
+08:34:17 gtmanbot > gtmanfred: TaDa!
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+[DEBUG ] Sending event: tag = salt/engines/ircbot/test/tag/ircbot; data = {\(aq_stamp\(aq: \(aq2016\-11\-28T14:34:16.633623\(aq, \(aqdata\(aq: [u\(aqirc\(aq, u\(aqis\(aq, u\(aqusefull\(aq]}
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.INDENT 0.0
.TP
.B class salt.engines.ircbot.Event(source, code, line)
.INDENT 7.0
.TP
+.B __getnewargs__()
+Return self as a plain tuple. Used by copy and pickle.
+.UNINDENT
+.INDENT 7.0
+.TP
+.B __getstate__()
+Exclude the OrderedDict from pickling
+.UNINDENT
+.INDENT 7.0
+.TP
+.B __repr__()
+Return a nicely formatted representation string
+.UNINDENT
+.INDENT 7.0
+.TP
.B code
Alias for field number 1
.UNINDENT
@@ -86929,6 +94232,21 @@ Alias for field number 0
.B class salt.engines.ircbot.PrivEvent(source, nick, user, host, code, channel, command, line)
.INDENT 7.0
.TP
+.B __getnewargs__()
+Return self as a plain tuple. Used by copy and pickle.
+.UNINDENT
+.INDENT 7.0
+.TP
+.B __getstate__()
+Exclude the OrderedDict from pickling
+.UNINDENT
+.INDENT 7.0
+.TP
+.B __repr__()
+Return a nicely formatted representation string
+.UNINDENT
+.INDENT 7.0
+.TP
.B channel
Alias for field number 5
.UNINDENT
@@ -87078,37 +94396,29 @@ pid
raw (the raw event data forwarded from the device)
.UNINDENT
.sp
-The topic title can consist of any of the combination of above fields,
-but the topic has to start with \(aqjnpr/syslog\(aq.
-So, we can have different combinations:
-.INDENT 0.0
-.INDENT 3.5
+The topic title can consist of any of the combination of above fields, but the
+topic has to start with \fBjnpr/syslog\fP\&. Here are a couple example
+combinations:
.INDENT 0.0
.IP \(bu 2
jnpr/syslog/hostip/daemon/event
.IP \(bu 2
jnpr/syslog/daemon/severity
.UNINDENT
-.UNINDENT
-.UNINDENT
.sp
The corresponding dynamic topic sent on salt event bus would look something like:
.INDENT 0.0
-.INDENT 3.5
-.INDENT 0.0
.IP \(bu 2
jnpr/syslog/1.1.1.1/mgd/UI_COMMIT_COMPLETED
.IP \(bu 2
jnpr/syslog/sshd/7
.UNINDENT
-.UNINDENT
-.UNINDENT
.sp
-The default topic title is \(aqjnpr/syslog/hostname/event\(aq.
+The default topic title is \fBjnpr/syslog/hostname/event\fP\&.
.sp
-The user can choose the type of data he/she wants of the event bus.
-Like, if one wants only events pertaining to a particular daemon, he/she can
-specify that in the configuration file:
+One can choose the type of data they want from the event bus. For example, if
+one wants only events pertaining to a particular daemon, this can be specified
+in the configuration file:
.INDENT 0.0
.INDENT 3.5
.sp
@@ -87120,7 +94430,7 @@ daemon: mgd
.UNINDENT
.UNINDENT
.sp
-One can even have a list of daemons like:
+One can even have a list of daemons:
.INDENT 0.0
.INDENT 3.5
.sp
@@ -87171,7 +94481,7 @@ Below is a sample syslog event which is received from the junos device:
.sp
.nf
.ft C
-\(aq<30>May 29 05:18:12 bng\-ui\-vm\-9 mspd[1492]: No chassis configuration found\(aq
+<30>May 29 05:18:12 bng\-ui\-vm\-9 mspd[1492]: No chassis configuration found
.ft P
.fi
.UNINDENT
@@ -87181,6 +94491,11 @@ The source for parsing the syslog messages is taken from:
\fI\%https://gist.github.com/leandrosilva/3651640#file\-xlog\-py\fP
.INDENT 0.0
.TP
+.B salt.engines.junos_syslog.__virtual__()
+Load only if twisted and pyparsing libs are present.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.engines.junos_syslog.start(port=516, **kwargs)
.UNINDENT
.SS salt.engines.logentries
@@ -87377,7 +94692,7 @@ Event example:
.sp
.nf
.ft C
-napalm/syslog/junos/BGP_PREFIX_THRESH_EXCEEDED/vmx01 {
+{
"_stamp": "2017\-05\-26T10:03:18.653045",
"error": "BGP_PREFIX_THRESH_EXCEEDED",
"host": "vmx01",
@@ -87434,9 +94749,9 @@ napalm/syslog/junos/BGP_PREFIX_THRESH_EXCEEDED/vmx01 {
.UNINDENT
.UNINDENT
.sp
-To consume the events and eventually react and deploy a configuration
-changes on the device(s) firing the event, one is able to
-identify the minion ID, using one of the following alternatives, but not limited to:
+To consume the events and eventually react and deploy a configuration changes
+on the device(s) firing the event, one is able to identify the minion ID, using
+one of the following alternatives, but not limited to:
.INDENT 0.0
.IP \(bu 2
\fBHost grains\fP to match the event tag
@@ -87449,11 +94764,11 @@ Define static grains
.IP \(bu 2
Write a grains module
.IP \(bu 2
-Targeting minions using pillar data \-\- the user
+Targeting minions using pillar data \- The user can
+configure certain information in the Pillar data and then use it to identify
+minions
.UNINDENT
.sp
-can insert certain information in the pillar and then use it to identify minions
-.sp
Master configuration example, to match the event and react:
.INDENT 0.0
.INDENT 3.5
@@ -87504,6 +94819,11 @@ can process the object from \fBopenconfig_structure\fP and define the bussiness
logic as required.
.INDENT 0.0
.TP
+.B salt.engines.napalm_syslog.__virtual__()
+Load only if napalm\-logs is installed.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.engines.napalm_syslog.start(transport=\(aqzmq\(aq, address=\(aq0.0.0.0\(aq, port=49017, auth_address=\(aq0.0.0.0\(aq, auth_port=49018, disable_security=False, certificate=None, os_whitelist=None, os_blacklist=None, error_whitelist=None, error_blacklist=None, host_whitelist=None, host_blacklist=None)
Listen to napalm\-logs and publish events into the Salt event bus.
.INDENT 7.0
@@ -87646,10 +94966,35 @@ engines:
.fi
.UNINDENT
.UNINDENT
-.INDENT 7.0
.TP
.B configuration
Example configuration using groups
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+engines:
+ \- slack:
+ token: \(aqxoxb\-xxxxxxxxxx\-xxxxxxxxxxxxxxxxxxxxxxxx\(aq
+ control: True
+ groups:
+ gods:
+ users:
+ \- garethgreenaway
+ commands:
+ \- test.ping
+ \- cmd.run
+ \- list_jobs
+ \- list_commands
+ aliases:
+ list_jobs:
+ cmd: jobs.list_jobs
+ list_commands:
+ cmd: pillar.get salt:engines:slack:valid_commands target=saltmaster tgt_type=list
+.ft P
+.fi
+.UNINDENT
.UNINDENT
.TP
.B depends
@@ -87885,6 +95230,173 @@ engines:
.UNINDENT
.UNINDENT
.UNINDENT
+.SS executors modules
+.TS
+center;
+|l|l|.
+_
+T{
+\fBdirect_call\fP
+T} T{
+Direct call executor module
+T}
+_
+T{
+\fBsplay\fP
+T} T{
+Splay function calls across targeted minions
+T}
+_
+T{
+\fBsudo\fP
+T} T{
+Sudo executor module
+T}
+_
+.TE
+.SS salt.executors.direct_call module
+.sp
+Direct call executor module
+.sp
+@author: Dmitry Kuzmenko <\fI\%dmitry.kuzmenko@dsr\-company.com\fP>
+.INDENT 0.0
+.TP
+.B class salt.executors.direct_call.DirectCallExecutor(opts, data, func, args, kwargs)
+Directly calls the given function with arguments
+.UNINDENT
+.SS salt.executors.splay module
+.sp
+Splay function calls across targeted minions
+.sp
+@author: Dmitry Kuzmenko <\fI\%dmitry.kuzmenko@dsr\-company.com\fP>
+.INDENT 0.0
+.TP
+.B class salt.executors.splay.SplayExecutor(opts, data, executor)
+classdocs
+.INDENT 7.0
+.TP
+.B execute()
+Splay a salt function call execution time across minions over
+a number of seconds (default: 600)
+.sp
+\fBNOTE:\fP
+.INDENT 7.0
+.INDENT 3.5
+You \fIprobably\fP want to use \-\-async here and look up the job results later.
+If you\(aqre dead set on getting the output from the CLI command, then make
+sure to set the timeout (with the \-t flag) to something greater than the
+splaytime (max splaytime + time to execute job).
+Otherwise, it\(aqs very likely that the cli will time out before the job returns.
+.UNINDENT
+.UNINDENT
+.sp
+CLI Example:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+# With default splaytime
+salt \-\-async \(aq*\(aq splay.splay pkg.install cowsay version=3.03\-8.el6
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+# With specified splaytime (5 minutes) and timeout with 10 second buffer
+salt \-t 310 \(aq*\(aq splay.splay 300 pkg.version cowsay
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.UNINDENT
+.UNINDENT
+.SS salt.executors.sudo module
+.sp
+Sudo executor module
+.sp
+@author: Dmitry Kuzmenko <\fI\%dmitry.kuzmenko@dsr\-company.com\fP>
+.INDENT 0.0
+.TP
+.B class salt.executors.sudo.SudoExecutor(opts, data, func, args, kwargs)
+Allow for the calling of execution modules via sudo.
+.sp
+This module is invoked by the minion if the \fBsudo_user\fP minion config is
+present.
+.sp
+Example minion config:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+sudo_user: saltdev
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Once this setting is made, any execution module call done by the minion will be
+run under \fBsudo \-u salt\-call\fP\&. For example, with the above
+minion config,
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+salt sudo_minion cmd.run \(aqcat /etc/sudoers\(aq
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+is equivalent to
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+sudo \-u saltdev salt\-call cmd.run \(aqcat /etc/sudoers\(aq
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+being run on \fBsudo_minion\fP\&.
+.INDENT 7.0
+.TP
+.B execute()
+Wrap a shell execution out to salt call with sudo
+.sp
+Example:
+.sp
+/etc/salt/minion
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+sudo_user: saltdev
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+salt \(aq*\(aq test.ping # is run as saltdev user
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.UNINDENT
+.UNINDENT
.SS fileserver modules
.TS
center;
@@ -88595,6 +96107,11 @@ unix
.sp
New in version 2016.11.0.
+.INDENT 0.0
+.TP
+.B salt.grains.napalm.__virtual__()
+NAPALM library must be installed for this module to work and run in a (proxy) minion.
+.UNINDENT
.INDENT 0.0
.TP
.B salt.grains.napalm.getos(proxy=None)
@@ -89174,7 +96691,6 @@ T{
\fBwin_pkg\fP
T} T{
Salt\(aqs Windows Package Manager
-\(ga
-.fi
-
+Bo Maryniuk <\fI\%bo@suse.de\fP>
.UNINDENT
T}
_
@@ -90337,6 +97976,12 @@ Salt interface to LDAP commands
T}
_
T{
+\fBlibcloud_dns\fP
+T} T{
+Connection module for Apache Libcloud DNS management
+T}
+_
+T{
\fBlinux_acl\fP
T} T{
Support for Linux File Access Control Lists
@@ -90609,7 +98254,7 @@ _
T{
\fBmsteams\fP
T} T{
-Module for sending messages to MS Teams ..
+Module for sending messages to MS Teams
T}
_
T{
@@ -90645,31 +98290,31 @@ _
T{
\fBnamecheap_dns\fP
T} T{
-Namecheap management
+Namecheap DNS Management
T}
_
T{
\fBnamecheap_domains\fP
T} T{
-Namecheap management
+Namecheap Domain Management
T}
_
T{
\fBnamecheap_ns\fP
T} T{
-Namecheap management
+Namecheap Nameserver Management
T}
_
T{
\fBnamecheap_ssl\fP
T} T{
-Namecheap management
+Namecheap SSL Certificate Management
T}
_
T{
\fBnamecheap_users\fP
T} T{
-Namecheap management
+Namecheap User Management
T}
_
T{
@@ -92047,7 +99692,12 @@ Be sure to set at least accept\-tos = True in cli.ini!
Most parameters will fall back to cli.ini defaults if None is given.
.INDENT 0.0
.TP
-.B salt.modules.acme.cert(name, aliases=None, email=None, webroot=None, test_cert=False, renew=None, keysize=None, server=None, owner=\(aqroot\(aq, group=\(aqroot\(aq, certname=None)
+.B salt.modules.acme.__virtual__()
+Only work when letsencrypt\-auto is installed
+.UNINDENT
+.INDENT 0.0
+.TP
+.B salt.modules.acme.cert(name, aliases=None, email=None, webroot=None, test_cert=False, renew=None, keysize=None, server=None, owner=\(aqroot\(aq, group=\(aqroot\(aq, mode=\(aq0640\(aq, certname=None)
Obtain/renew a certificate from an ACME CA, probably Let\(aqs Encrypt.
.INDENT 7.0
.TP
@@ -92070,9 +99720,11 @@ Obtain/renew a certificate from an ACME CA, probably Let\(aqs Encrypt.
.IP \(bu 2
\fBserver\fP \-\- API endpoint to talk to
.IP \(bu 2
-\fBowner\fP \-\- owner of private key
+\fBowner\fP \-\- owner of the private key file
.IP \(bu 2
-\fBgroup\fP \-\- group of private key
+\fBgroup\fP \-\- group of the private key file
+.IP \(bu 2
+\fBmode\fP \-\- mode of the private key file
.IP \(bu 2
\fBcertname\fP \-\- Name of the certificate to save
.UNINDENT
@@ -92243,6 +99895,11 @@ minion, and it is using a different module (or gives an error similar to
.UNINDENT
.INDENT 0.0
.TP
+.B salt.modules.aix_group.__virtual__()
+Set the group module if the kernel is AIX
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.aix_group.add(name, gid=None, system=False, root=None)
Add the specified group
.sp
@@ -92493,6 +100150,11 @@ Radek Rada <\fI\%radek.rada@gmail.com\fP>
.UNINDENT
.INDENT 0.0
.TP
+.B salt.modules.alternatives.__virtual__()
+Only if alternatives dir is available
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.alternatives.auto(name)
Trigger alternatives to set the path for as
specified by priority.
@@ -92668,6 +100330,11 @@ Debian\-based system is detected.
.UNINDENT
.INDENT 0.0
.TP
+.B salt.modules.apache.__virtual__()
+Only load the module if apache is installed
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.apache.config(name, config, edit=True)
Create VirtualHost configuration files
.INDENT 7.0
@@ -92925,6 +100592,11 @@ salt \-t 10 \(aq*\(aq apache.vhosts
Module for apcupsd
.INDENT 0.0
.TP
+.B salt.modules.apcups.__virtual__()
+Provides apcupsd only if apcaccess is present
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.apcups.status()
Return apcaccess output
.sp
@@ -93009,6 +100681,11 @@ Linux
.UNINDENT
.INDENT 0.0
.TP
+.B salt.modules.apf.__virtual__()
+Only load if apf exists on the system
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.apf.allow(ip, port=None)
Add host (IP/FQDN) to allow_hosts.rules and immediately load new rule into firewall
CLI Example:
@@ -93149,6 +100826,11 @@ minion, and it is using a different module (or gives an error similar to
.UNINDENT
.INDENT 0.0
.TP
+.B salt.modules.apk.__virtual__()
+Confirm this module is running on an Alpine Linux distribution
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.apk.file_dict(*packages)
List the files that belong to a package, grouped by package. Not
specifying any packages will return a list of _every_ file on the system\(aqs
@@ -93495,6 +101177,11 @@ For repository management, the \fBpython\-apt\fP package must be installed.
.UNINDENT
.INDENT 0.0
.TP
+.B salt.modules.aptpkg.__virtual__()
+Confirm this module is on a Debian\-based system
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.aptpkg.add_repo_key(path=None, text=None, keyserver=None, keyid=None, saltenv=\(aqbase\(aq)
New in version 2017.7.0.
@@ -95523,6 +103210,11 @@ salt \(aq*\(aq archive.zip /tmp/zipfile.zip \(aq/tmp/sourcefile*\(aq
Module for fetching artifacts from Artifactory
.INDENT 0.0
.TP
+.B salt.modules.artifactory.__virtual__()
+Only load if elementtree xml library is available.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.artifactory.get_latest_release(artifactory_url, repository, group_id, artifact_id, packaging, target_dir=\(aq/tmp\(aq, target_file=None, classifier=None, username=None, password=None)
Gets the latest release of the artifact
.INDENT 7.0
@@ -95689,6 +103381,11 @@ linux,openbsd,freebsd
.sp
Changed in version 2017.7.0.
+.INDENT 0.0
+.TP
+.B salt.modules.at.__virtual__()
+Most everything has the ability to support at(1)
+.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.at.at(*args, **kwargs)
@@ -95814,6 +103511,11 @@ solaris,illumos,smartso
.sp
New in version 2017.7.0.
+.INDENT 0.0
+.TP
+.B salt.modules.at_solaris.__virtual__()
+We only deal with Solaris\(aq specific version of at
+.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.at_solaris.at(*args, **kwargs)
@@ -95947,6 +103649,11 @@ known to resolve the issue.
.UNINDENT
.INDENT 0.0
.TP
+.B salt.modules.augeas_cfg.__virtual__()
+Only run this module if the augeas python module is installed
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.augeas_cfg.execute(context=None, lens=None, commands=(), load_path=None)
Execute Augeas commands
.sp
@@ -96421,6 +104128,11 @@ New in version 2015.8.0.
Requires a \fBsubdomain\fP and an \fBapikey\fP in \fB/etc/salt/minion\fP:
.INDENT 0.0
.TP
+.B salt.modules.bamboohr.__virtual__()
+Only load the module if apache is installed
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.bamboohr.list_employees(order_by=\(aqid\(aq)
Show all employees for this company.
.sp
@@ -96580,6 +104292,11 @@ It\(aqs available in Linux mainline kernel since 3.10
This module needs the bcache userspace tools to function.
.INDENT 0.0
.TP
+.B salt.modules.bcache.__virtual__()
+Only work when make\-bcache is installed
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.bcache.attach(dev=None)
Attach a backing devices to a cache set
If no dev is given, all backing devices will be attached.
@@ -97156,6 +104873,11 @@ f5_bigip_11.6
.UNINDENT
.INDENT 0.0
.TP
+.B salt.modules.bigip.__virtual__()
+Only return if requests is installed
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.bigip.add_pool_member(hostname, username, password, name, member)
A function to connect to a bigip device and add a new member to an existing pool.
.INDENT 7.0
@@ -98659,6 +106381,11 @@ New in version 2014.7.0.
.sp
Deprecated since version 2016.11.0: Merged to \fIdisk\fP module
+.INDENT 0.0
+.TP
+.B salt.modules.blockdev.__virtual__()
+Only load this module if the blockdev utility is available
+.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.blockdev.format(device, fs_type=\(aqext4\(aq, inode_size=None, lazy_itable_init=None, force=False)
@@ -98758,6 +106485,11 @@ pybluez >= 0.18
.UNINDENT
.INDENT 0.0
.TP
+.B salt.modules.bluez.__virtual__()
+Only load the module if bluetooth is installed
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.bluez.address()
Get the many addresses of the Bluetooth adapter
.sp
@@ -99044,6 +106776,12 @@ boto3
.UNINDENT
.INDENT 0.0
.TP
+.B salt.modules.boto3_elasticache.__virtual__()
+Only load if boto libraries exist and if boto libraries are greater than
+a given version.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.boto3_elasticache.add_tags_to_resource(name, region=None, key=None, keyid=None, profile=None, **args)
Add tags to an Elasticache resource.
.sp
@@ -99651,6 +107389,12 @@ boto3
.UNINDENT
.INDENT 0.0
.TP
+.B salt.modules.boto3_route53.__virtual__()
+Only load if boto libraries exist and if boto libraries are greater than
+a given version.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.boto3_route53.associate_vpc_with_hosted_zone(HostedZoneId=None, Name=None, VPCId=None, VPCName=None, VPCRegion=None, Comment=None, region=None, key=None, keyid=None, profile=None)
Associates an Amazon VPC with a private hosted zone.
.sp
@@ -99707,9 +107451,6 @@ salt myminion boto3_route53.associate_vpc_with_hosted_zone N
.INDENT 0.0
.TP
.B salt.modules.boto3_route53.change_resource_record_sets(HostedZoneId=None, Name=None, PrivateZone=None, ChangeBatch=None, region=None, key=None, keyid=None, profile=None)
-Ugh!!! Not gonna try to reproduce and validatethis mess in here \- just pass what we get to AWS
-and let it decide if it\(aqs valid or not...
-.sp
See the \fI\%AWS Route53 API docs\fP as well as the \fI\%Boto3 documentation\fP for all the details...
.sp
The syntax for a ChangeBatch parameter is as follows, but note that the permutations of allowed
@@ -99720,82 +107461,44 @@ highly recommended for any non\-trival configurations.
.sp
.nf
.ft C
-
+{
+ "Comment": "string",
+ "Changes": [
+ {
+ "Action": "CREATE"|"DELETE"|"UPSERT",
+ "ResourceRecordSet": {
+ "Name": "string",
+ "Type": "SOA"|"A"|"TXT"|"NS"|"CNAME"|"MX"|"NAPTR"|"PTR"|"SRV"|"SPF"|"AAAA",
+ "SetIdentifier": "string",
+ "Weight": 123,
+ "Region": "us\-east\-1"|"us\-east\-2"|"us\-west\-1"|"us\-west\-2"|"ca\-central\-1"|"eu\-west\-1"|"eu\-west\-2"|"eu\-central\-1"|"ap\-southeast\-1"|"ap\-southeast\-2"|"ap\-northeast\-1"|"ap\-northeast\-2"|"sa\-east\-1"|"cn\-north\-1"|"ap\-south\-1",
+ "GeoLocation": {
+ "ContinentCode": "string",
+ "CountryCode": "string",
+ "SubdivisionCode": "string"
+ },
+ "Failover": "PRIMARY"|"SECONDARY",
+ "TTL": 123,
+ "ResourceRecords": [
+ {
+ "Value": "string"
+ },
+ ],
+ "AliasTarget": {
+ "HostedZoneId": "string",
+ "DNSName": "string",
+ "EvaluateTargetHealth": True|False
+ },
+ "HealthCheckId": "string",
+ "TrafficPolicyInstanceId": "string"
+ }
+ },
+ ]
+}
.ft P
.fi
.UNINDENT
.UNINDENT
-.INDENT 7.0
-.TP
-.B ChangeBatch={
-\(aqComment\(aq: \(aqstring\(aq,
-\(aqChanges\(aq: [
-.INDENT 7.0
-.INDENT 3.5
-.INDENT 0.0
-.TP
-.B {
-\(aqAction\(aq: \(aqCREATE\(aq|\(aqDELETE\(aq|\(aqUPSERT\(aq,
-\(aqResourceRecordSet\(aq: {
-.INDENT 7.0
-.INDENT 3.5
-\(aqName\(aq: \(aqstring\(aq,
-\(aqType\(aq: \(aqSOA\(aq|\(aqA\(aq|\(aqTXT\(aq|\(aqNS\(aq|\(aqCNAME\(aq|\(aqMX\(aq|\(aqNAPTR\(aq|\(aqPTR\(aq|\(aqSRV\(aq|\(aqSPF\(aq|\(aqAAAA\(aq,
-\(aqSetIdentifier\(aq: \(aqstring\(aq,
-\(aqWeight\(aq: 123,
-\(aqRegion\(aq: \(aqus\-east\-1\(aq|\(aqus\-east\-2\(aq|\(aqus\-west\-1\(aq|\(aqus\-west\-2\(aq|\(aqca\-central\-1\(aq|\(aqeu\-west\-1\(aq|\(aqeu\-west\-2\(aq|\(aqeu\-central\-1\(aq|\(aqap\-southeast\-1\(aq|\(aqap\-southeast\-2\(aq|\(aqap\-northeast\-1\(aq|\(aqap\-northeast\-2\(aq|\(aqsa\-east\-1\(aq|\(aqcn\-north\-1\(aq|\(aqap\-south\-1\(aq,
-\(aqGeoLocation\(aq: {
-.INDENT 0.0
-.INDENT 3.5
-\(aqContinentCode\(aq: \(aqstring\(aq,
-\(aqCountryCode\(aq: \(aqstring\(aq,
-\(aqSubdivisionCode\(aq: \(aqstring\(aq
-.UNINDENT
-.UNINDENT
-.sp
-},
-\(aqFailover\(aq: \(aqPRIMARY\(aq|\(aqSECONDARY\(aq,
-\(aqTTL\(aq: 123,
-\(aqResourceRecords\(aq: [
-.INDENT 0.0
-.INDENT 3.5
-.INDENT 0.0
-.TP
-.B {
-\(aqValue\(aq: \(aqstring\(aq
-.UNINDENT
-.sp
-},
-.UNINDENT
-.UNINDENT
-.sp
-],
-\(aqAliasTarget\(aq: {
-.INDENT 0.0
-.INDENT 3.5
-\(aqHostedZoneId\(aq: \(aqstring\(aq,
-\(aqDNSName\(aq: \(aqstring\(aq,
-\(aqEvaluateTargetHealth\(aq: True|False
-.UNINDENT
-.UNINDENT
-.sp
-},
-\(aqHealthCheckId\(aq: \(aqstring\(aq,
-\(aqTrafficPolicyInstanceId\(aq: \(aqstring\(aq
-.UNINDENT
-.UNINDENT
-.sp
-}
-.UNINDENT
-.sp
-},
-.UNINDENT
-.UNINDENT
-.sp
-]
-.UNINDENT
-.sp
-}
.sp
CLI Example:
.INDENT 7.0
@@ -100182,6 +107885,9 @@ salt myminion boto3_route53.update_hosted_zone_comment Name=example.org.
.SS salt.modules.boto_apigateway module
.sp
Connection module for Amazon APIGateway
+.sp
+New in version 2016.11.0.
+
.INDENT 0.0
.TP
.B configuration
@@ -100305,6 +108011,12 @@ boto3
.UNINDENT
.INDENT 0.0
.TP
+.B salt.modules.boto_apigateway.__virtual__()
+Only load if boto libraries exist and if boto libraries are greater than
+a given version.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.boto_apigateway.activate_api_deployment(restApiId, stageName, deploymentId, region=None, key=None, keyid=None, profile=None)
Activates previously deployed deployment for a given stage
.sp
@@ -101434,6 +109146,11 @@ boto3
.UNINDENT
.INDENT 0.0
.TP
+.B salt.modules.boto_asg.__virtual__()
+Only load if boto libraries exist.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.boto_asg.create(name, launch_config_name, availability_zones, min_size, max_size, desired_capacity=None, load_balancers=None, default_cooldown=None, health_check_type=None, health_check_period=None, placement_group=None, vpc_zone_identifier=None, tags=None, termination_policies=None, suspended_processes=None, scaling_policies=None, scheduled_actions=None, region=None, notification_arn=None, notification_types=None, key=None, keyid=None, profile=None)
Create an autoscale group.
.sp
@@ -101810,6 +109527,11 @@ boto
.UNINDENT
.INDENT 0.0
.TP
+.B salt.modules.boto_cfn.__virtual__()
+Only load if boto libraries exist.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.boto_cfn.create(name, template_body=None, template_url=None, parameters=None, notification_arns=None, disable_rollback=None, timeout_in_minutes=None, capabilities=None, tags=None, on_failure=None, stack_policy_body=None, stack_policy_url=None, region=None, key=None, keyid=None, profile=None)
Create a CFN stack.
.sp
@@ -102018,6 +109740,12 @@ myprofile:
.UNINDENT
.INDENT 0.0
.TP
+.B salt.modules.boto_cloudtrail.__virtual__()
+Only load if boto libraries exist and if boto libraries are greater than
+a given version.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.boto_cloudtrail.add_tags(Name, region=None, key=None, keyid=None, profile=None, **kwargs)
Add tags to a trail
.sp
@@ -102339,6 +110067,11 @@ boto
.UNINDENT
.INDENT 0.0
.TP
+.B salt.modules.boto_cloudwatch.__virtual__()
+Only load if boto libraries exist.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.boto_cloudwatch.convert_to_arn(arns, region=None, key=None, keyid=None, profile=None)
Convert a list of strings into actual arns. Converts convenience names such
as \(aqscaling_policy:...\(aq
@@ -102554,6 +110287,11 @@ boto3
.UNINDENT
.INDENT 0.0
.TP
+.B salt.modules.boto_cloudwatch_event.__virtual__()
+Only load if boto libraries exist.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.boto_cloudwatch_event.create_or_update(Name, ScheduleExpression=None, EventPattern=None, Description=None, RoleArn=None, State=None, region=None, key=None, keyid=None, profile=None)
Given a valid config, create an event rule.
.sp
@@ -102835,6 +110573,12 @@ boto3
.UNINDENT
.INDENT 0.0
.TP
+.B salt.modules.boto_cognitoidentity.__virtual__()
+Only load if boto libraries exist and if boto libraries are greater than
+a given version.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.boto_cognitoidentity.create_identity_pool(IdentityPoolName, AllowUnauthenticatedIdentities=False, SupportedLoginProviders=None, DeveloperProviderName=None, OpenIdConnectProviderARNs=None, region=None, key=None, keyid=None, profile=None)
Creates a new identity pool. All parameters except for IdentityPoolName is optional.
SupportedLoginProviders should be a dictionary mapping provider names to provider app
@@ -102984,6 +110728,11 @@ boto3
.UNINDENT
.INDENT 0.0
.TP
+.B salt.modules.boto_datapipeline.__virtual__()
+Only load if boto3 libraries exists.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.boto_datapipeline.activate_pipeline(pipeline_id, region=None, key=None, keyid=None, profile=None)
Start processing pipeline tasks. This function is idempotent.
.sp
@@ -103192,6 +110941,11 @@ boto
.UNINDENT
.INDENT 0.0
.TP
+.B salt.modules.boto_dynamodb.__virtual__()
+Only load if boto libraries exist.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.boto_dynamodb.create_global_secondary_index(table_name, global_index, region=None, key=None, keyid=None, profile=None)
Creates a single global secondary index on a DynamoDB table.
.sp
@@ -103333,21 +111087,12 @@ New in version 2015.8.0.
This module accepts explicit EC2 credentials but can also
utilize IAM roles assigned to the instance through Instance Profiles.
Dynamic credentials are then automatically obtained from AWS API and no
-further configuration is necessary. More Information available at:
-.INDENT 7.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/iam\-roles\-for\-amazon\-ec2.html
-.ft P
-.fi
-.UNINDENT
+further configuration is necessary. More Information available \fI\%here\fP\&.
.UNINDENT
.sp
If IAM roles are not used you need to specify them either in a pillar or
in the minion\(aqs config file:
-.INDENT 7.0
+.INDENT 0.0
.INDENT 3.5
.sp
.nf
@@ -103360,7 +111105,7 @@ ec2.key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs
.UNINDENT
.sp
A region may also be specified in the configuration:
-.INDENT 7.0
+.INDENT 0.0
.INDENT 3.5
.sp
.nf
@@ -103375,7 +111120,7 @@ If a region is not specified, the default is us\-east\-1.
.sp
It\(aqs also possible to specify key, keyid, and region via a profile, either
as a passed in dict, or as a string to pull from pillars or minion config:
-.INDENT 7.0
+.INDENT 0.0
.INDENT 3.5
.sp
.nf
@@ -103388,12 +111133,19 @@ myprofile:
.fi
.UNINDENT
.UNINDENT
+.INDENT 0.0
.TP
.B depends
boto
.UNINDENT
.INDENT 0.0
.TP
+.B salt.modules.boto_ec2.__virtual__()
+Only load if boto libraries exist and if boto libraries are greater than
+a given version.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.boto_ec2.allocate_eip_address(domain=None, region=None, key=None, keyid=None, profile=None)
Allocate a new Elastic IP address and associate it with your account.
.INDENT 7.0
@@ -103930,40 +111682,49 @@ New in version 2016.11.0.
associated with those in the list will be returned.
.TP
.B filters
+(dict) \- Additional constraints on which volumes to return. Valid filters are:
+.UNINDENT
.INDENT 7.0
-.TP
-.B (dict) \- Additional constraints on which volumes to return. Valid filters are:
+.IP \(bu 2
attachment.attach\-time \- The time stamp when the attachment initiated.
+.IP \(bu 2
attachment.delete\-on\-termination \- Whether the volume is deleted on instance termination.
+.IP \(bu 2
attachment.device \- The device name that is exposed to the instance (for example, /dev/sda1).
+.IP \(bu 2
attachment.instance\-id \- The ID of the instance the volume is attached to.
+.IP \(bu 2
attachment.status \- The attachment state (attaching | attached | detaching | detached).
+.IP \(bu 2
availability\-zone \- The Availability Zone in which the volume was created.
+.IP \(bu 2
create\-time \- The time stamp when the volume was created.
+.IP \(bu 2
encrypted \- The encryption status of the volume.
+.IP \(bu 2
size \- The size of the volume, in GiB.
+.IP \(bu 2
snapshot\-id \- The snapshot from which the volume was created.
+.IP \(bu 2
status \- The status of the volume (creating | available | in\-use | deleting | deleted | error).
+.IP \(bu 2
\fI\%tag:key=value\fP \- The key/value combination of a tag assigned to the resource.
+.IP \(bu 2
volume\-id \- The volume ID.
-volume\-type \- The Amazon EBS volume type. This can be gp2 for General Purpose SSD, io1 for
+.IP \(bu 2
+volume\-type \- The Amazon EBS volume type. This can be \fBgp2\fP for General
+Purpose SSD, \fBio1\fP for Provisioned IOPS SSD, \fBst1\fP for Throughput
+Optimized HDD, \fBsc1\fP for Cold HDD, or \fBstandard\fP for Magnetic volumes.
+.UNINDENT
.INDENT 7.0
-.INDENT 3.5
-Provisioned IOPS SSD, st1 for Throughput Optimized HDD, sc1 for Cold HDD, or
-standard for Magnetic volumes.
-.UNINDENT
-.UNINDENT
-.UNINDENT
.TP
.B return_objs
-(bool) \- Changes the return type from list of volume IDs to list of boto.ec2.volume.Volume objects
+(bool) \- Changes the return type from list of volume IDs to list of
+boto.ec2.volume.Volume objects
.TP
.B returns
-.INDENT 7.0
-.TP
-.B (list) \- A list of the requested values: Either the volume IDs; or, if return_objs is true,
-boto.ec2.volume.Volume objects.
-.UNINDENT
+(list) \- A list of the requested values: Either the volume IDs or, if
+return_objs is \fBTrue\fP, boto.ec2.volume.Volume objects.
.UNINDENT
.sp
CLI Example:
@@ -104354,32 +112115,27 @@ assign the instance a specific available IP address from the subnet
data structure describing the EBS volumes associated with the Image.
(string) \- A string representation of a BlockDeviceMapping structure
(dict) \- A dict describing a BlockDeviceMapping structure
+.sp
YAML example:
-.. code\-block:: yaml
.INDENT 7.0
.INDENT 3.5
-.INDENT 0.0
-.TP
-.B device\-maps:
-.INDENT 7.0
-.TP
-.B /dev/sdb:
-ephemeral_name: ephemeral0
-.TP
-.B /dev/sdc:
-ephemeral_name: ephemeral1
-.TP
-.B /dev/sdd:
-ephemeral_name: ephemeral2
-.TP
-.B /dev/sde:
-ephemeral_name: ephemeral3
-.TP
-.B /dev/sdf:
-size: 20
-volume_type: gp2
-.UNINDENT
-.UNINDENT
+.sp
+.nf
+.ft C
+device\-maps:
+ /dev/sdb:
+ ephemeral_name: ephemeral0
+ /dev/sdc:
+ ephemeral_name: ephemeral1
+ /dev/sdd:
+ ephemeral_name: ephemeral2
+ /dev/sde:
+ ephemeral_name: ephemeral3
+ /dev/sdf:
+ size: 20
+ volume_type: gp2
+.ft P
+.fi
.UNINDENT
.UNINDENT
.TP
@@ -104514,6 +112270,36 @@ The default set of states is (\(aqpending\(aq, \(aqrebooting\(aq, \(aqrunning\(a
.sp
YAML example fragment:
.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+\- filters:
+ attachment.instance_id: i\-abcdef12
+ tags:
+ Name: dev\-int\-abcdef12.aws\-foo.com
+\- filters:
+ attachment.device: /dev/sdf
+ tags:
+ ManagedSnapshots: true
+ BillingGroup: bubba.hotep@aws\-foo.com
+ in_states:
+ \- stopped
+ \- terminated
+\- filters:
+ instance_name: prd\-foo\-01.aws\-foo.com
+ tags:
+ Name: prd\-foo\-01.aws\-foo.com
+ BillingGroup: infra\-team@aws\-foo.com
+\- filters:
+ volume_ids: [ vol\-12345689, vol\-abcdef12 ]
+ tags:
+ BillingGroup: infra\-team@aws\-foo.com
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.INDENT 7.0
.TP
.B authoritative (bool)
If true, any existing tags on the matched volumes, and not explicitly requested here, will
@@ -104658,6 +112444,12 @@ boto3
.UNINDENT
.INDENT 0.0
.TP
+.B salt.modules.boto_efs.__virtual__()
+Only load if boto3 libraries exist and if boto3 libraries are greater than
+a given version.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.boto_efs.create_file_system(name, performance_mode=\(aqgeneralPurpose\(aq, keyid=None, key=None, profile=None, region=None, **kwargs)
Creates a new, empty file system.
.INDENT 7.0
@@ -104674,6 +112466,16 @@ generalPurpose or maxIO
.UNINDENT
.sp
CLI Example:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+salt \(aqmy\-minion\(aq boto_efs.create_file_system efs\-name generalPurpose
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
@@ -104717,6 +112519,16 @@ These must be for the same VPC as subnet specified.
.UNINDENT
.sp
CLI Example:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+salt \(aqmy\-minion\(aq boto_efs.create_mount_target filesystemid subnetid
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
@@ -104735,6 +112547,16 @@ its value with the value provided in the request.
.UNINDENT
.sp
CLI Example:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+salt \(aqmy\-minion\(aq boto_efs.create_tags
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
@@ -104751,6 +112573,16 @@ you must first delete them.
.UNINDENT
.sp
CLI Example:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+salt \(aqmy\-minion\(aq boto_efs.delete_file_system filesystemid
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
@@ -104773,6 +112605,16 @@ You can mount an EC2 instance in your VPC via another mount target.
.UNINDENT
.sp
CLI Example:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+salt \(aqmy\-minion\(aq boto_efs.delete_mount_target mounttargetid
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
@@ -104788,6 +112630,16 @@ Deletes the specified tags from a file system.
.UNINDENT
.sp
CLI Example:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+salt \(aqmy\-minion\(aq boto_efs.delete_tags
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
@@ -104804,6 +112656,16 @@ if filesystemid is specified
.UNINDENT
.sp
CLI Example:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+salt \(aqmy\-minion\(aq boto_efs.get_file_systems efs\-id
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
@@ -104832,6 +112694,16 @@ Must be specified if filesystemid is not
.UNINDENT
.sp
CLI Example:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+salt \(aqmy\-minion\(aq boto_efs.get_mount_targets
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
@@ -104847,6 +112719,16 @@ Return the tags associated with an EFS instance.
.UNINDENT
.sp
CLI Example:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+salt \(aqmy\-minion\(aq boto_efs.get_tags efs\-id
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
@@ -104862,6 +112744,16 @@ Modifies the set of security groups in effect for a mount target
.UNINDENT
.sp
CLI Example:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+salt \(aqmy\-minion\(aq boto_efs.set_security_groups my\-mount\-target\-id my\-sec\-group
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
.UNINDENT
.SS salt.modules.boto_elasticache
.sp
@@ -104936,6 +112828,11 @@ boto
.UNINDENT
.INDENT 0.0
.TP
+.B salt.modules.boto_elasticache.__virtual__()
+Only load if boto libraries exist.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.boto_elasticache.authorize_cache_security_group_ingress(name, ec2_security_group_name, ec2_security_group_owner_id, region=None, key=None, keyid=None, profile=None)
Authorize network ingress from an ec2 security group to a cache security
group.
@@ -105403,6 +113300,12 @@ boto3
.UNINDENT
.INDENT 0.0
.TP
+.B salt.modules.boto_elasticsearch_domain.__virtual__()
+Only load if boto libraries exist and if boto libraries are greater than
+a given version.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.boto_elasticsearch_domain.add_tags(DomainName=None, ARN=None, region=None, key=None, keyid=None, profile=None, **kwargs)
Add tags to a domain
.sp
@@ -105681,6 +113584,11 @@ boto >= 2.33.0
.UNINDENT
.INDENT 0.0
.TP
+.B salt.modules.boto_elb.__virtual__()
+Only load if boto libraries exist.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.boto_elb.apply_security_groups(name, security_groups, region=None, key=None, keyid=None, profile=None)
Apply security groups to ELB.
.sp
@@ -106309,6 +114217,11 @@ myprofile:
.UNINDENT
.INDENT 0.0
.TP
+.B salt.modules.boto_elbv2.__virtual__()
+Only load if boto3 libraries exist.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.boto_elbv2.deregister_targets(name, targets, region=None, key=None, keyid=None, profile=None)
Deregister targets to a target froup of an ALB. \fBtargets\fP is either a
instance id string or a list of instance id\(aqs.
@@ -106455,6 +114368,11 @@ boto
.UNINDENT
.INDENT 0.0
.TP
+.B salt.modules.boto_iam.__virtual__()
+Only load if boto libraries exist.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.boto_iam.add_user_to_group(user_name, group_name, region=None, key=None, keyid=None, profile=None)
Add user to group.
.sp
@@ -108020,6 +115938,12 @@ myprofile:
.UNINDENT
.INDENT 0.0
.TP
+.B salt.modules.boto_iot.__virtual__()
+Only load if boto libraries exist and if boto libraries are greater than
+a given version.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.boto_iot.attach_principal_policy(policyName, principal, region=None, key=None, keyid=None, profile=None)
Attach the specified policy to the specified principal (certificate or other
credential.)
@@ -108665,6 +116589,11 @@ boto3
.UNINDENT
.INDENT 0.0
.TP
+.B salt.modules.boto_kinesis.__virtual__()
+Only load if boto3 libraries exist.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.boto_kinesis.create_stream(stream_name, num_shards, region=None, key=None, keyid=None, profile=None)
Create a stream with name stream_name and initial number of shards num_shards.
.sp
@@ -108941,6 +116870,11 @@ boto
.UNINDENT
.INDENT 0.0
.TP
+.B salt.modules.boto_kms.__virtual__()
+Only load if boto libraries exist.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.boto_kms.create_alias(alias_name, target_key_id, region=None, key=None, keyid=None, profile=None)
Create a display name for a key.
.sp
@@ -109323,13 +117257,13 @@ New in version 2016.3.0.
.INDENT 0.0
.TP
.B depends
-.INDENT 7.0
+.UNINDENT
+.INDENT 0.0
.IP \(bu 2
boto
.IP \(bu 2
boto3
.UNINDENT
-.UNINDENT
.sp
The dependencies listed above can be installed via package or pip.
.INDENT 0.0
@@ -109338,21 +117272,12 @@ The dependencies listed above can be installed via package or pip.
This module accepts explicit Lambda credentials but can also
utilize IAM roles assigned to the instance through Instance Profiles.
Dynamic credentials are then automatically obtained from AWS API and no
-further configuration is necessary. More Information available at:
-.INDENT 7.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/iam\-roles\-for\-amazon\-ec2.html
-.ft P
-.fi
-.UNINDENT
+further configuration is necessary. More Information available \fI\%here\fP\&.
.UNINDENT
.sp
If IAM roles are not used you need to specify them either in a pillar or
in the minion\(aqs config file:
-.INDENT 7.0
+.INDENT 0.0
.INDENT 3.5
.sp
.nf
@@ -109365,7 +117290,7 @@ lambda.key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs
.UNINDENT
.sp
A region may also be specified in the configuration:
-.INDENT 7.0
+.INDENT 0.0
.INDENT 3.5
.sp
.nf
@@ -109380,7 +117305,7 @@ If a region is not specified, the default is us\-east\-1.
.sp
It\(aqs also possible to specify key, keyid and region via a profile, either
as a passed in dict, or as a string to pull from pillars or minion config:
-.INDENT 7.0
+.INDENT 0.0
.INDENT 3.5
.sp
.nf
@@ -109393,7 +117318,6 @@ myprofile:
.fi
.UNINDENT
.UNINDENT
-.UNINDENT
.sp
Changed in version 2015.8.0: All methods now return a dictionary. Create and delete methods return:
.INDENT 0.0
@@ -109448,6 +117372,12 @@ error:
.UNINDENT
.UNINDENT
+.INDENT 0.0
+.TP
+.B salt.modules.boto_lambda.__virtual__()
+Only load if boto libraries exist and if boto libraries are greater than
+a given version.
+.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.boto_lambda.add_permission(FunctionName, StatementId, Action, Principal, SourceArn=None, SourceAccount=None, Qualifier=None, region=None, key=None, keyid=None, profile=None)
@@ -109535,33 +117465,33 @@ salt myminion boto_lamba.create_event_source_mapping arn::::eventsource myfuncti
.INDENT 0.0
.TP
.B salt.modules.boto_lambda.create_function(FunctionName, Runtime, Role, Handler, ZipFile=None, S3Bucket=None, S3Key=None, S3ObjectVersion=None, Description=\(aq\(aq, Timeout=3, MemorySize=128, Publish=False, WaitForRole=False, RoleRetries=5, region=None, key=None, keyid=None, profile=None, VpcConfig=None, Environment=None)
+New in version 2017.7.0.
+
+.sp
Given a valid config, create a function.
.INDENT 7.0
.TP
.B Environment
The parent object that contains your environment\(aqs configuration
-settings. This is a dictionary of the form:
-{
+settings. This is a dictionary of the form:
.INDENT 7.0
.INDENT 3.5
-.INDENT 0.0
-.TP
-.B \(aqVariables\(aq: {
-\(aqVariableName\(aq: \(aqVariableValue\(aq
-.UNINDENT
.sp
+.nf
+.ft C
+{
+ \(aqVariables\(aq: {
+ \(aqVariableName\(aq: \(aqVariableValue\(aq
+ }
}
+.ft P
+.fi
+.UNINDENT
.UNINDENT
.UNINDENT
.sp
-}
-.sp
-New in version 2017.7.0.
-
-.UNINDENT
-.sp
-Returns {created: true} if the function was created and returns
-{created: False} if the function was not created.
+Returns \fB{\(aqcreated\(aq: True}\fP if the function was created and \fB{created:
+False}\fP if the function was not created.
.sp
CLI Example:
.INDENT 7.0
@@ -109894,33 +117824,33 @@ salt myminion boto_lamba.update_function_code my_function ZipFile=function.zip
.INDENT 0.0
.TP
.B salt.modules.boto_lambda.update_function_config(FunctionName, Role=None, Handler=None, Description=None, Timeout=None, MemorySize=None, region=None, key=None, keyid=None, profile=None, VpcConfig=None, WaitForRole=False, RoleRetries=5, Environment=None)
+New in version 2017.7.0.
+
+.sp
Update the named lambda function to the configuration.
.INDENT 7.0
.TP
.B Environment
The parent object that contains your environment\(aqs configuration
-settings. This is a dictionary of the form:
-{
+settings. This is a dictionary of the form:
.INDENT 7.0
.INDENT 3.5
-.INDENT 0.0
-.TP
-.B \(aqVariables\(aq: {
-\(aqVariableName\(aq: \(aqVariableValue\(aq
-.UNINDENT
.sp
+.nf
+.ft C
+{
+ \(aqVariables\(aq: {
+ \(aqVariableName\(aq: \(aqVariableValue\(aq
+ }
}
+.ft P
+.fi
+.UNINDENT
.UNINDENT
.UNINDENT
.sp
-}
-.sp
-New in version 2017.7.0.
-
-.UNINDENT
-.sp
-Returns {updated: true} if the function was updated and returns
-{updated: False} if the function was not updated.
+Returns \fB{\(aqupdated\(aq: True}\fP if the function was updated, and
+\fB{\(aqupdated\(aq: False}\fP if the function was not updated.
.sp
CLI Example:
.INDENT 7.0
@@ -110007,6 +117937,12 @@ boto3
.UNINDENT
.INDENT 0.0
.TP
+.B salt.modules.boto_rds.__virtual__()
+Only load if boto libraries exist and if boto libraries are greater than
+a given version.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.boto_rds.create(name, allocated_storage, db_instance_class, engine, master_username, master_user_password, db_name=None, db_security_groups=None, vpc_security_group_ids=None, availability_zone=None, db_subnet_group_name=None, preferred_maintenance_window=None, db_parameter_group_name=None, backup_retention_period=None, preferred_backup_window=None, port=None, multi_az=None, engine_version=None, auto_minor_version_upgrade=None, license_model=None, iops=None, option_group_name=None, character_set_name=None, publicly_accessible=None, wait_status=None, tags=None, db_cluster_identifier=None, storage_type=None, tde_credential_arn=None, tde_credential_password=None, storage_encrypted=None, kms_key_id=None, domain=None, copy_tags_to_snapshot=None, monitoring_interval=None, monitoring_role_arn=None, domain_iam_role_name=None, region=None, promotion_tier=None, key=None, keyid=None, profile=None)
Create an RDS
.sp
@@ -110399,6 +118335,11 @@ boto
.UNINDENT
.INDENT 0.0
.TP
+.B salt.modules.boto_route53.__virtual__()
+Only load if boto libraries exist.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.boto_route53.add_record(name, value, zone, record_type, identifier=None, ttl=None, region=None, key=None, keyid=None, profile=None, wait_for_sync=True, split_dns=False, private_zone=False, retry_on_rate_limit=True, rate_limit_retries=5)
Add a record to a zone.
.sp
@@ -110807,6 +118748,12 @@ myprofile:
.UNINDENT
.INDENT 0.0
.TP
+.B salt.modules.boto_s3_bucket.__virtual__()
+Only load if boto libraries exist and if boto libraries are greater than
+a given version.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.boto_s3_bucket.create(Bucket, ACL=None, LocationConstraint=None, GrantFullControl=None, GrantRead=None, GrantReadACP=None, GrantWrite=None, GrantWriteACP=None, region=None, key=None, keyid=None, profile=None)
Given a valid config, create an S3 Bucket.
.sp
@@ -111421,6 +119368,12 @@ boto
.UNINDENT
.INDENT 0.0
.TP
+.B salt.modules.boto_secgroup.__virtual__()
+Only load if boto libraries exist and if boto libraries are greater than
+a given version.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.boto_secgroup.authorize(name=None, source_group_name=None, source_group_owner_id=None, ip_protocol=None, from_port=None, to_port=None, cidr_ip=None, group_id=None, source_group_group_id=None, region=None, key=None, keyid=None, profile=None, vpc_id=None, vpc_name=None, egress=False)
Add a new rule to an existing security group.
.sp
@@ -111764,6 +119717,11 @@ boto
.UNINDENT
.INDENT 0.0
.TP
+.B salt.modules.boto_sns.__virtual__()
+Only load if boto libraries exist.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.boto_sns.create(name, region=None, key=None, keyid=None, profile=None)
Create an SNS topic.
.sp
@@ -111974,6 +119932,11 @@ boto
.UNINDENT
.INDENT 0.0
.TP
+.B salt.modules.boto_sqs.__virtual__()
+Only load if boto libraries exist.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.boto_sqs.create(name, region=None, key=None, keyid=None, profile=None)
Create an SQS queue.
.sp
@@ -112119,21 +120082,12 @@ boto3 >= 1.2.6
This module accepts explicit VPC credentials but can also
utilize IAM roles assigned to the instance through Instance Profiles.
Dynamic credentials are then automatically obtained from AWS API and no
-further configuration is necessary. More Information available at:
-.INDENT 7.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/iam\-roles\-for\-amazon\-ec2.html
-.ft P
-.fi
-.UNINDENT
+further configuration is necessary. More Information available \fI\%here\fP\&.
.UNINDENT
.sp
If IAM roles are not used you need to specify them either in a pillar or
in the minion\(aqs config file:
-.INDENT 7.0
+.INDENT 0.0
.INDENT 3.5
.sp
.nf
@@ -112146,7 +120100,7 @@ vpc.key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs
.UNINDENT
.sp
A region may also be specified in the configuration:
-.INDENT 7.0
+.INDENT 0.0
.INDENT 3.5
.sp
.nf
@@ -112161,7 +120115,7 @@ If a region is not specified, the default is us\-east\-1.
.sp
It\(aqs also possible to specify key, keyid and region via a profile, either
as a passed in dict, or as a string to pull from pillars or minion config:
-.INDENT 7.0
+.INDENT 0.0
.INDENT 3.5
.sp
.nf
@@ -112174,7 +120128,6 @@ myprofile:
.fi
.UNINDENT
.UNINDENT
-.UNINDENT
.sp
Changed in version 2015.8.0: All methods now return a dictionary. Create and delete methods return:
.INDENT 0.0
@@ -112304,6 +120257,12 @@ salt myminion boto_vpc.delete_vpc_peering_connection conn_id=pcx\-8a8939e3
.UNINDENT
.INDENT 0.0
.TP
+.B salt.modules.boto_vpc.__virtual__()
+Only load if boto libraries exist and if boto libraries are greater than
+a given version.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.boto_vpc.accept_vpc_peering_connection(conn_id=\(aq\(aq, name=\(aq\(aq, region=None, key=None, keyid=None, profile=None, dry_run=False)
Request a VPC peering connection between two VPCs.
.sp
@@ -112319,15 +120278,20 @@ New in version 2016.11.0.
\fBname\fP \-\- The name of this VPC peering connection. String type.
.IP \(bu 2
\fBregion\fP \-\- The AWS region to use. Type string.
+.IP \(bu 2
+\fBkey\fP \-\- The key to use for this connection. Type string.
+.IP \(bu 2
+\fBkeyid\fP \-\- The key id to use.
+.IP \(bu 2
+\fBprofile\fP \-\- The profile to use.
+.IP \(bu 2
+\fBdry_run\fP \-\- The dry_run flag to set.
.UNINDENT
+.TP
+.B Returns
+dict
.UNINDENT
.sp
-:param key. The key to use for this connection. Type string.
-:param keyid. The key id to use.
-:param profile. The profile to use.
-:param dry_run. The dry_run flag to set.
-:return: dict
-.sp
Warning: Please specify either the \fBvpc_peering_connection_id\fP or
\fBname\fP but not both. Specifying both will result in an error!
.sp
@@ -113729,6 +121693,11 @@ Note that npm, git and bower must be installed for this module to be
available.
.INDENT 0.0
.TP
+.B salt.modules.bower.__virtual__()
+Only work when Bower is installed
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.bower.install(pkg, dir, pkgs=None, runas=None, env=None)
Install a Bower package.
.sp
@@ -113870,6 +121839,12 @@ salt \(aq*\(aq bower.uninstall underscore /path/to/project
Module for gathering and managing bridging information
.INDENT 0.0
.TP
+.B salt.modules.bridge.__virtual__()
+Confirm this module is supported by the OS and the system has
+required tools
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.bridge.add(br=None)
Creates a bridge
.sp
@@ -114193,6 +122168,11 @@ salt \(aq*\(aq shadow.set_password someuser \(aq$1$UYCIxa628.9qXjpQCjM4a..\(aq
Module for managing BTRFS file systems.
.INDENT 0.0
.TP
+.B salt.modules.btrfs.__virtual__()
+Only work on POSIX\-like systems
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.btrfs.add(mountpoint, *devices, **kwargs)
Add a devices to a BTRFS filesystem.
.sp
@@ -114232,7 +122212,7 @@ General options:
.IP \(bu 2
.INDENT 2.0
.TP
-\fBkeeplf\fP: Keep \fBlost+found\fP of the partition (removed by default,
+.B \fBkeeplf\fP: Keep \fBlost+found\fP of the partition (removed by default,
but still in the image, if not permanent migration)
.UNINDENT
.UNINDENT
@@ -114370,13 +122350,13 @@ Options:
.IP \(bu 2
.INDENT 2.0
.TP
-\fBdto\fP: (raid0|raid1|raid5|raid6|raid10|single|dup)
+.B \fBdto\fP: (raid0|raid1|raid5|raid6|raid10|single|dup)
Specify how the data must be spanned across the devices specified.
.UNINDENT
.IP \(bu 2
.INDENT 2.0
.TP
-\fBmto\fP: (raid0|raid1|raid5|raid6|raid10|single|dup)
+.B \fBmto\fP: (raid0|raid1|raid5|raid6|raid10|single|dup)
Specify how metadata must be spanned across the devices specified.
.UNINDENT
.IP \(bu 2
@@ -114492,6 +122472,11 @@ salt \(aq*\(aq btrfs.version
.sp
New in version 2015.8.0.
+.INDENT 0.0
+.TP
+.B salt.modules.cabal.__virtual__()
+Only work when cabal\-install is installed.
+.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.cabal.install(pkg=None, pkgs=None, user=None, install_global=False, env=None)
@@ -114646,6 +122631,11 @@ Capirca is not yet available on PyPI threrefore it has to be installed
directly form Git: \fBpip install \-e git+git@github.com:google/capirca.git#egg=aclgen\fP\&.
.INDENT 0.0
.TP
+.B salt.modules.capirca_acl.__virtual__()
+This module requires at least Capirca to work.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.capirca_acl.get_filter_config(platform, filter_name, filter_options=None, terms=None, prepend=True, pillar_key=\(aqacl\(aq, pillarenv=None, saltenv=None, merge_pillar=True, only_lower_merge=False, revision_id=None, revision_no=None, revision_date=True, revision_date_format=\(aq%Y/%m/%d\(aq)
Return the configuration of a policy filter.
.INDENT 7.0
@@ -115017,11 +123007,7 @@ A special service to choose from. This is a helper so the user is able to
select a source just using the name, instead of specifying a destination_port and protocol.
Allows the same options as \fBsource_service\fP\&.
.TP
-.B
-.nf
-**
-.fi
-term_fields
+.B term_fields
Term attributes.
To see what fields are supported, please consult the list of supported \fI\%keywords\fP\&.
Some platforms have few other \fI\%optional\fP keywords.
@@ -115373,6 +123359,11 @@ cassandra.thrift_port: 9160
.UNINDENT
.INDENT 0.0
.TP
+.B salt.modules.cassandra.__virtual__()
+Only load if pycassa is available and the system is configured
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.cassandra.column_families(keyspace=None)
Return existing column families for all keyspaces
or just the provided one.
@@ -115637,6 +123628,19 @@ cassandra:
.UNINDENT
.INDENT 0.0
.TP
+.B salt.modules.cassandra_cql.__virtual__()
+Return virtual name of the module only if the python driver can be loaded.
+.INDENT 7.0
+.TP
+.B Returns
+The virtual name of the module.
+.TP
+.B Return type
+\fI\%str\fP
+.UNINDENT
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.cassandra_cql.cql_query(query, contact_points=None, port=None, cql_user=None, cql_pass=None)
Run a query on a Cassandra cluster and return a dictionary.
.INDENT 7.0
@@ -116214,6 +124218,11 @@ A new app (and thus new connections) is created for each task execution
.UNINDENT
.INDENT 0.0
.TP
+.B salt.modules.celery.__virtual__()
+Only load if celery libraries exist.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.celery.run_task(task_name, args=None, kwargs=None, broker=None, backend=None, wait_for_result=False, timeout=None, propagate=True, interval=0.5, no_ack=True, raise_timeout=True, config=None)
Execute celery tasks. For celery specific parameters see celery documentation.
.sp
@@ -116286,6 +124295,18 @@ New in version 2016.11.0.
.TP
.B salt.modules.ceph.ceph_version()
Get the version of ceph installed
+.sp
+CLI Example:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+salt \(aq*\(aq ceph.ceph_version
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
@@ -116305,27 +124326,19 @@ salt \(aq*\(aq ceph.cluster_quorum \e
.fi
.UNINDENT
.UNINDENT
-.sp
-Notes:
-Get the cluster quorum status.
-.sp
-Scope:
-Cluster wide
-.sp
-Arguments:
.INDENT 7.0
.TP
.B cluster_uuid
-Set the cluster UUID. Defaults to value found in ceph config file.
+The cluster UUID. Defaults to value found in ceph config file.
.TP
.B cluster_name
-Set the cluster name. Defaults to "ceph".
+The cluster name. Defaults to \fBceph\fP\&.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.ceph.cluster_status(**kwargs)
-Get the cluster status
+Get the cluster status, including health if in quorum
.sp
CLI Example:
.INDENT 7.0
@@ -116340,27 +124353,19 @@ salt \(aq*\(aq ceph.cluster_status \e
.fi
.UNINDENT
.UNINDENT
-.sp
-Notes:
-Get the cluster status including health if in quorum.
-.sp
-Scope:
-Cluster wide
-.sp
-Arguments:
.INDENT 7.0
.TP
.B cluster_uuid
-Set the cluster UUID. Defaults to value found in ceph config file.
+The cluster UUID. Defaults to value found in ceph config file.
.TP
.B cluster_name
-Set the cluster name. Defaults to "ceph".
+The cluster name. Defaults to \fBceph\fP\&.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.ceph.keyring_auth_add(**kwargs)
-Add keyring to authorised list
+Add keyring to authorized list
.sp
CLI Example:
.INDENT 7.0
@@ -116376,24 +124381,16 @@ salt \(aq*\(aq ceph.keyring_auth_add \e
.fi
.UNINDENT
.UNINDENT
-.sp
-Notes:
.INDENT 7.0
.TP
-.B keyring_type
-Required parameter
-Can be set to:
-.INDENT 7.0
-.INDENT 3.5
-admin, mon, osd, rgw, mds
-.UNINDENT
-.UNINDENT
+.B keyring_type (required)
+One of \fBadmin\fP, \fBmon\fP, \fBosd\fP, \fBrgw\fP, \fBmds\fP
.TP
.B cluster_uuid
-Set the cluster UUID. Defaults to value found in ceph config file.
+The cluster UUID. Defaults to value found in ceph config file.
.TP
.B cluster_name
-Set the cluster name. Defaults to "ceph".
+The cluster name. Defaults to \fBceph\fP\&.
.UNINDENT
.UNINDENT
.INDENT 0.0
@@ -116415,24 +124412,16 @@ salt \(aq*\(aq ceph.keyring_osd_auth_del \e
.fi
.UNINDENT
.UNINDENT
-.sp
-Notes:
.INDENT 7.0
.TP
-.B keyring_type
-Required parameter
-Can be set to:
-.INDENT 7.0
-.INDENT 3.5
-admin, mon, osd, rgw, mds
-.UNINDENT
-.UNINDENT
+.B keyring_type (required)
+One of \fBadmin\fP, \fBmon\fP, \fBosd\fP, \fBrgw\fP, \fBmds\fP
.TP
.B cluster_uuid
-Set the cluster UUID. Defaults to value found in ceph config file.
+The cluster UUID. Defaults to value found in ceph config file.
.TP
.B cluster_name
-Set the cluster name. Defaults to "ceph".
+The cluster name. Defaults to \fBceph\fP\&.
.UNINDENT
.UNINDENT
.INDENT 0.0
@@ -116453,15 +124442,13 @@ salt \(aq*\(aq ceph.keyring_auth_list \e
.fi
.UNINDENT
.UNINDENT
-.sp
-Notes:
.INDENT 7.0
.TP
.B cluster_name
-Set the cluster name. Defaults to "ceph".
+The cluster name. Defaults to \fBceph\fP\&.
.TP
.B cluster_uuid
-Set the cluster UUID. Defaults to value found in ceph config file.
+The cluster UUID. Defaults to value found in ceph config file.
.UNINDENT
.UNINDENT
.INDENT 0.0
@@ -116483,30 +124470,22 @@ salt \(aq*\(aq ceph.keyring_create \e
.fi
.UNINDENT
.UNINDENT
-.sp
-Notes:
.INDENT 7.0
.TP
-.B keyring_type
-Required parameter
-Can be set to:
-.INDENT 7.0
-.INDENT 3.5
-admin, mon, osd, rgw, mds
-.UNINDENT
-.UNINDENT
+.B keyring_type (required)
+One of \fBadmin\fP, \fBmon\fP, \fBosd\fP, \fBrgw\fP, \fBmds\fP
.TP
.B cluster_uuid
-Set the cluster UUID. Defaults to value found in ceph config file.
+The cluster UUID. Defaults to value found in ceph config file.
.TP
.B cluster_name
-Set the cluster name. Defaults to "ceph".
+The cluster name. Defaults to \fBceph\fP\&.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.ceph.keyring_present(**kwargs)
-Is keyring on disk
+Returns \fBTrue\fP if the keyring is present on disk, otherwise \fBFalse\fP
.sp
CLI Example:
.INDENT 7.0
@@ -116522,24 +124501,16 @@ salt \(aq*\(aq ceph.keyring_present \e
.fi
.UNINDENT
.UNINDENT
-.sp
-Notes:
.INDENT 7.0
.TP
-.B keyring_type
-Required parameter
-Can be set to:
-.INDENT 7.0
-.INDENT 3.5
-admin, mon, osd, rgw, mds
-.UNINDENT
-.UNINDENT
+.B keyring_type (required)
+One of \fBadmin\fP, \fBmon\fP, \fBosd\fP, \fBrgw\fP, \fBmds\fP
.TP
.B cluster_uuid
-Set the cluster UUID. Defaults to value found in ceph config file.
+The cluster UUID. Defaults to value found in ceph config file.
.TP
.B cluster_name
-Set the cluster name. Defaults to "ceph".
+The cluster name. Defaults to \fBceph\fP\&.
.UNINDENT
.UNINDENT
.INDENT 0.0
@@ -116561,24 +124532,16 @@ salt \(aq*\(aq ceph.keyring_purge \e
.fi
.UNINDENT
.UNINDENT
-.sp
-Notes:
.INDENT 7.0
.TP
-.B keyring_type
-Required parameter
-Can be set to:
-.INDENT 7.0
-.INDENT 3.5
-admin, mon, osd, rgw, mds
-.UNINDENT
-.UNINDENT
+.B keyring_type (required)
+One of \fBadmin\fP, \fBmon\fP, \fBosd\fP, \fBrgw\fP, \fBmds\fP
.TP
.B cluster_uuid
-Set the cluster UUID. Defaults to value found in ceph config file.
+The cluster UUID. Defaults to value found in ceph config file.
.TP
.B cluster_name
-Set the cluster name. Defaults to "ceph".
+The cluster name. Defaults to \fBceph\fP\&.
.UNINDENT
.sp
If no ceph config file is found, this command will fail.
@@ -116597,30 +124560,21 @@ CLI Example:
salt \(aq*\(aq ceph.keyring_save \e
\(aqkeyring_type\(aq=\(aqadmin\(aq \e
\(aqcluster_name\(aq=\(aqceph\(aq \e
- \(aqcluster_uuid\(aq=\(aqcluster_uuid\(aq \e
- \(aq\(aq
+ \(aqcluster_uuid\(aq=\(aqcluster_uuid\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
-.sp
-Notes:
.INDENT 7.0
.TP
-.B keyring_type
-Required parameter
-Can be set to:
-.INDENT 7.0
-.INDENT 3.5
-admin, mon, osd, rgw, mds
-.UNINDENT
-.UNINDENT
+.B keyring_type (required)
+One of \fBadmin\fP, \fBmon\fP, \fBosd\fP, \fBrgw\fP, \fBmds\fP
.TP
.B cluster_uuid
-Set the cluster UUID. Defaults to value found in ceph config file.
+The cluster UUID. Defaults to value found in ceph config file.
.TP
.B cluster_name
-Set the cluster name. Defaults to "ceph".
+The cluster name. Defaults to \fBceph\fP\&.
.UNINDENT
.UNINDENT
.INDENT 0.0
@@ -116644,27 +124598,22 @@ salt \(aq*\(aq ceph.mds_create \e
.fi
.UNINDENT
.UNINDENT
-.sp
-Notes:
.INDENT 7.0
.TP
-.B name:
-Required parameter
-Set the rgw client name. Must start with \(aqmds.\(aq
+.B name (required)
+The MDS name (must start with \fBmds.\fP)
.TP
-.B port:
-Required parameter
-Port for the mds to listen to.
+.B port (required)
+Port to which the MDS will listen
.TP
-.B addr:
-Required parameter
-Address or IP address for the mds to listen to.
+.B addr (required)
+Address or IP address for the MDS to listen
.TP
.B cluster_uuid
-Set the cluster UUID. Defaults to value found in ceph config file.
+The cluster UUID. Defaults to value found in ceph config file.
.TP
.B cluster_name
-Set the cluster name. Defaults to "ceph".
+The cluster name. Defaults to \fBceph\fP\&.
.UNINDENT
.UNINDENT
.INDENT 0.0
@@ -116686,25 +124635,22 @@ salt \(aq*\(aq ceph.mds_destroy \e
.fi
.UNINDENT
.UNINDENT
-.sp
-Notes:
.INDENT 7.0
.TP
-.B name:
-Required parameter
-Set the rgw client name. Must start with \(aqmds.\(aq
+.B name (required)
+The MDS name (must start with \fBmds.\fP)
.TP
.B cluster_uuid
-Set the cluster UUID. Defaults to value found in ceph config file.
+The cluster UUID. Defaults to value found in ceph config file.
.TP
.B cluster_name
-Set the cluster name. Defaults to "ceph".
+The cluster name. Defaults to \fBceph\fP\&.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.ceph.mon_active(**kwargs)
-Is mon daemon running
+Returns \fBTrue\fP if the mon daemon is running, otherwise \fBFalse\fP
.sp
CLI Example:
.INDENT 7.0
@@ -116719,15 +124665,13 @@ salt \(aq*\(aq ceph.mon_active \e
.fi
.UNINDENT
.UNINDENT
-.sp
-Notes:
.INDENT 7.0
.TP
.B cluster_uuid
-Set the cluster UUID. Defaults to value found in ceph config file.
+The cluster UUID. Defaults to value found in ceph config file.
.TP
.B cluster_name
-Set the cluster name. Defaults to "ceph".
+The cluster name. Defaults to \fBceph\fP\&.
.UNINDENT
.UNINDENT
.INDENT 0.0
@@ -116748,21 +124692,19 @@ salt \(aq*\(aq ceph.mon_create \e
.fi
.UNINDENT
.UNINDENT
-.sp
-Notes:
.INDENT 7.0
.TP
.B cluster_uuid
-Set the cluster UUID. Defaults to value found in ceph config file.
+The cluster UUID. Defaults to value found in ceph config file.
.TP
.B cluster_name
-Set the cluster name. Defaults to "ceph".
+The cluster name. Defaults to \fBceph\fP\&.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.ceph.mon_is(**kwargs)
-Is this a mon node
+Returns \fBTrue\fP if the target is a mon node, otherwise \fBFalse\fP
.sp
CLI Example:
.INDENT 7.0
@@ -116777,21 +124719,19 @@ salt \(aq*\(aq ceph.mon_is \e
.fi
.UNINDENT
.UNINDENT
-.sp
-Notes:
.INDENT 7.0
.TP
.B cluster_name
-Set the cluster name. Defaults to "ceph".
+The cluster name. Defaults to \fBceph\fP\&.
.TP
.B cluster_uuid
-Set the cluster UUID. Defaults to value found in ceph config file.
+The cluster UUID. Defaults to value found in ceph config file.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.ceph.mon_quorum(**kwargs)
-Is mon daemon in quorum
+Returns \fBTrue\fP if the mon daemon is in the quorum, otherwise \fBFalse\fP
.sp
CLI Example:
.INDENT 7.0
@@ -116806,15 +124746,13 @@ salt \(aq*\(aq ceph.mon_quorum \e
.fi
.UNINDENT
.UNINDENT
-.sp
-Notes:
.INDENT 7.0
.TP
.B cluster_uuid
-Set the cluster UUID. Defaults to value found in ceph config file.
+The cluster UUID. Defaults to value found in ceph config file.
.TP
.B cluster_name
-Set the cluster name. Defaults to "ceph".
+The cluster name. Defaults to \fBceph\fP\&.
.UNINDENT
.UNINDENT
.INDENT 0.0
@@ -116835,15 +124773,13 @@ salt \(aq*\(aq ceph.mon_status \e
.fi
.UNINDENT
.UNINDENT
-.sp
-Notes:
.INDENT 7.0
.TP
.B cluster_uuid
-Set the cluster UUID. Defaults to value found in ceph config file.
+The cluster UUID. Defaults to value found in ceph config file.
.TP
.B cluster_name
-Set the cluster name. Defaults to "ceph".
+The cluster name. Defaults to \fBceph\fP\&.
.UNINDENT
.UNINDENT
.INDENT 0.0
@@ -116883,7 +124819,7 @@ salt \(aq*\(aq ceph.osd_discover
.INDENT 0.0
.TP
.B salt.modules.ceph.osd_prepare(**kwargs)
-prepare an OSD
+Prepare an OSD
.sp
CLI Example:
.INDENT 7.0
@@ -116902,21 +124838,19 @@ salt \(aq*\(aq ceph.osd_prepare \(aqosd_dev\(aq=\(aq/dev/vdc\(aq \e
.fi
.UNINDENT
.UNINDENT
-.sp
-Notes:
.INDENT 7.0
.TP
.B cluster_uuid
-Set the device to store the osd data on.
+The device to store the osd data on.
.TP
.B journal_dev
-Set the journal device. defaults to osd_dev.
+The journal device. defaults to osd_dev.
.TP
.B cluster_name
-Set the cluster name. Defaults to "ceph".
+The cluster name. Defaults to \fBceph\fP\&.
.TP
.B cluster_uuid
-Set the cluster date will be added too. Defaults to the value found in local config.
+The cluster date will be added too. Defaults to the value found in local config.
.TP
.B osd_fs_type
set the file system to store OSD data with. Defaults to "xfs".
@@ -116939,13 +124873,11 @@ CLI Example:
.sp
.nf
.ft C
-
+salt \(aq*\(aq ceph.partition_is /dev/sdc1
.ft P
.fi
.UNINDENT
.UNINDENT
-.sp
-salt \(aq*\(aq ceph.partition_is /dev/sdc1
.UNINDENT
.INDENT 0.0
.TP
@@ -117016,15 +124948,13 @@ salt \(aq*\(aq ceph.pool_add pool_name \e
.fi
.UNINDENT
.UNINDENT
-.sp
-Notes:
.INDENT 7.0
.TP
.B cluster_name
-Set the cluster name. Defaults to "ceph".
+The cluster name. Defaults to \fBceph\fP\&.
.TP
.B cluster_uuid
-Set the cluster UUID. Defaults to value found in ceph config file.
+The cluster UUID. Defaults to value found in ceph config file.
.TP
.B pg_num
Default to 8
@@ -117036,10 +124966,10 @@ Default to pg_num
can take values "replicated" or "erasure"
.TP
.B erasure_code_profile
-Set the "erasure_code_profile"
+The "erasure_code_profile"
.TP
.B crush_ruleset
-Set the crush map rule set
+The crush map rule set
.UNINDENT
.UNINDENT
.INDENT 0.0
@@ -117060,15 +124990,13 @@ salt \(aq*\(aq ceph.pool_del pool_name \e
.fi
.UNINDENT
.UNINDENT
-.sp
-Notes:
.INDENT 7.0
.TP
.B cluster_name
-Set the cluster name. Defaults to "ceph".
+The cluster name. Defaults to \fBceph\fP\&.
.TP
.B cluster_uuid
-Set the cluster UUID. Defaults to value found in ceph config file.
+The cluster UUID. Defaults to value found in ceph config file.
.UNINDENT
.UNINDENT
.INDENT 0.0
@@ -117089,15 +125017,13 @@ salt \(aq*\(aq ceph.pool_list \e
.fi
.UNINDENT
.UNINDENT
-.sp
-Notes:
.INDENT 7.0
.TP
.B cluster_name
-Set the cluster name. Defaults to "ceph".
+The cluster name. Defaults to \fBceph\fP\&.
.TP
.B cluster_uuid
-Set the cluster UUID. Defaults to value found in ceph config file.
+The cluster UUID. Defaults to value found in ceph config file.
.UNINDENT
.UNINDENT
.INDENT 0.0
@@ -117118,15 +125044,13 @@ salt \(aq*\(aq ceph.purge \e
.fi
.UNINDENT
.UNINDENT
-.sp
-Notes:
.INDENT 7.0
.TP
.B cluster_name
-Set the cluster name. Defaults to "ceph".
+The cluster name. Defaults to \fBceph\fP\&.
.TP
.B cluster_uuid
-Set the cluster UUID. Defaults to value found in ceph config file.
+The cluster UUID. Defaults to value found in ceph config file.
.UNINDENT
.UNINDENT
.INDENT 0.0
@@ -117148,19 +125072,16 @@ salt \(aq*\(aq ceph.rgw_create \e
.fi
.UNINDENT
.UNINDENT
-.sp
-Notes:
.INDENT 7.0
.TP
-.B name:
-Required parameter
-Set the rgw client name. Must start with \(aqrgw.\(aq
+.B name (required)
+The RGW client name. Must start with \fBrgw.\fP
.TP
.B cluster_uuid
-Set the cluster UUID. Defaults to value found in ceph config file.
+The cluster UUID. Defaults to value found in ceph config file.
.TP
.B cluster_name
-Set the cluster name. Defaults to "ceph".
+The cluster name. Defaults to \fBceph\fP\&.
.UNINDENT
.UNINDENT
.INDENT 0.0
@@ -117182,19 +125103,16 @@ salt \(aq*\(aq ceph.rgw_destroy \e
.fi
.UNINDENT
.UNINDENT
-.sp
-Notes:
.INDENT 7.0
.TP
-.B name:
-Required parameter
-Set the rgw client name. Must start with \(aqrgw.\(aq
+.B name (required)
+The RGW client name (must start with \fBrgw.\fP)
.TP
.B cluster_uuid
-Set the cluster UUID. Defaults to value found in ceph config file.
+The cluster UUID. Defaults to value found in ceph config file.
.TP
.B cluster_name
-Set the cluster name. Defaults to "ceph".
+The cluster name. Defaults to \fBceph\fP\&.
.UNINDENT
.UNINDENT
.INDENT 0.0
@@ -117213,15 +125131,13 @@ salt \(aq*\(aq ceph.rgw_pools_create
.fi
.UNINDENT
.UNINDENT
-.sp
-Notes:
.INDENT 7.0
.TP
.B cluster_uuid
-Set the cluster UUID. Defaults to value found in ceph config file.
+The cluster UUID. Defaults to value found in ceph config file.
.TP
.B cluster_name
-Set the cluster name. Defaults to "ceph".
+The cluster name. Defaults to \fBceph\fP\&.
.UNINDENT
.UNINDENT
.INDENT 0.0
@@ -117240,15 +125156,13 @@ salt \(aq*\(aq ceph.rgw_pools_missing
.fi
.UNINDENT
.UNINDENT
-.sp
-Notes:
.INDENT 7.0
.TP
.B cluster_uuid
-Set the cluster UUID. Defaults to value found in ceph config file.
+The cluster UUID. Defaults to value found in ceph config file.
.TP
.B cluster_name
-Set the cluster name. Defaults to "ceph".
+The cluster name. Defaults to \fBceph\fP\&.
.UNINDENT
.UNINDENT
.INDENT 0.0
@@ -117267,19 +125181,16 @@ salt \(aq*\(aq ceph.osd_prepare \(aqdev\(aq=\(aq/dev/vdc\(aq \e
.fi
.UNINDENT
.UNINDENT
-.sp
-Notes:
.INDENT 7.0
.TP
.B dev
The block device to format.
.TP
.B cluster_name
-Set the cluster name. Defaults to "ceph".
+The cluster name. Defaults to \fBceph\fP\&.
.TP
.B cluster_uuid
-Set the cluster date will be added too. Defaults to the value found in
-local config.
+The cluster UUID. Defaults to value found in ceph config file.
.UNINDENT
.UNINDENT
.SS salt.modules.chassis
@@ -117297,11 +125208,21 @@ parameter in \fBsalt.modules.dracr\fP and calls it.
.sp
New in version 2015.8.2.
+.INDENT 0.0
+.TP
+.B salt.modules.chassis.__virtual__()
+Only work on proxy
+.UNINDENT
.SS salt.modules.chef
.sp
Execute chef in server or solo mode
.INDENT 0.0
.TP
+.B salt.modules.chef.__virtual__()
+Only load if chef is installed
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.chef.client(whyrun=False, localmode=False, logfile=None, **kwargs)
Execute a chef client run and return a dict with the stderr, stdout,
return code, and pid.
@@ -117441,6 +125362,16 @@ A dead simple module wrapping calls to the Chocolatey package manager
.sp
New in version 2014.1.0.
+.INDENT 0.0
+.TP
+.B salt.modules.chocolatey.__virtual__()
+Confirm this module is on a Windows system running Vista or later.
+.sp
+While it is possible to make Chocolatey run under XP and Server 2003 with
+an awful lot of hassle (e.g. SSL is completely broken), the PowerShell shim
+for simulating UAC forces a GUI prompt, and is not compatible with
+salt\-minion running as SYSTEM.
+.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.chocolatey.add_source(name, source_location, username=None, password=None)
@@ -118383,6 +126314,11 @@ salt cisco\-nso cisconso.set_data_value running \(aqdevices/ex0/routes\(aq 10.0.
Salt\-specific interface for calling Salt Cloud directly
.INDENT 0.0
.TP
+.B salt.modules.cloud.__virtual__()
+Only work on POSIX\-like systems
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.cloud.action(fun=None, cloudmap=None, names=None, provider=None, instance=None, **kwargs)
Execute a single action on the given provider/instance
.sp
@@ -118783,6 +126719,12 @@ Keep in mind that this module is insecure, in that it can give whomever has
access to the master root execution access to all salt minions.
.INDENT 0.0
.TP
+.B salt.modules.cmdmod.__virtual__()
+Overwriting the cmd python module makes debugging modules
+with pdb a bit harder so lets do it this way instead.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.cmdmod.exec_code(lang, code, cwd=None)
Pass in two strings, the first naming the executable language, aka \-
python2, python3, ruby, perl, lua, etc. the second string containing
@@ -121094,6 +129036,11 @@ salt \(aq*\(aq cmd.which_bin \(aq[pip2, pip, pip\-python]\(aq
Use composer to install PHP dependencies for a directory
.INDENT 0.0
.TP
+.B salt.modules.composer.__virtual__()
+Always load
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.composer.did_composer_install(dir)
Test to see if the vendor directory exists in this directory
.INDENT 7.0
@@ -121868,8 +129815,7 @@ CLI Example:
.sp
.nf
.ft C
-salt \(aq*\(aq consul.agent_check_fail checkid=\(aqredis_check1\(aq
- note=\(aqForcing check into critical state.\(aq
+salt \(aq*\(aq consul.agent_check_fail checkid=\(aqredis_check1\(aq note=\(aqForcing check into critical state.\(aq
.ft P
.fi
.UNINDENT
@@ -121903,8 +129849,7 @@ CLI Example:
.sp
.nf
.ft C
-salt \(aq*\(aq consul.agent_check_pass checkid=\(aqredis_check1\(aq
- note=\(aqForcing check into passing state.\(aq
+salt \(aq*\(aq consul.agent_check_pass checkid=\(aqredis_check1\(aq note=\(aqForcing check into passing state.\(aq
.ft P
.fi
.UNINDENT
@@ -121952,8 +129897,7 @@ CLI Example:
.sp
.nf
.ft C
-salt \(aq*\(aq consul.agent_check_register name=\(aqMemory Utilization\(aq
- script=\(aq/usr/local/bin/check_mem.py\(aq interval=\(aq15s\(aq
+salt \(aq*\(aq consul.agent_check_register name=\(aqMemory Utilization\(aq script=\(aq/usr/local/bin/check_mem.py\(aq interval=\(aq15s\(aq
.ft P
.fi
.UNINDENT
@@ -121987,8 +129931,7 @@ CLI Example:
.sp
.nf
.ft C
-salt \(aq*\(aq consul.agent_check_warn checkid=\(aqredis_check1\(aq
- note=\(aqForcing check into warning state.\(aq
+salt \(aq*\(aq consul.agent_check_warn checkid=\(aqredis_check1\(aq note=\(aqForcing check into warning state.\(aq
.ft P
.fi
.UNINDENT
@@ -122227,8 +130170,7 @@ CLI Example:
.sp
.nf
.ft C
-salt \(aq*\(aq consul.agent_service_deregister serviceid=\(aqredis\(aq
- enable=\(aqTrue\(aq reason=\(aqDown for upgrade\(aq
+salt \(aq*\(aq consul.agent_service_deregister serviceid=\(aqredis\(aq enable=\(aqTrue\(aq reason=\(aqDown for upgrade\(aq
.ft P
.fi
.UNINDENT
@@ -122283,9 +130225,7 @@ CLI Example:
.sp
.nf
.ft C
-salt \(aq*\(aq consul.agent_service_register name=\(aqredis\(aq
- tags=\(aq["master", "v1"]\(aq address="127.0.0.1" port="8080"
- check_script="/usr/local/bin/check_redis.py" interval="10s"
+salt \(aq*\(aq consul.agent_service_register name=\(aqredis\(aq tags=\(aq["master", "v1"]\(aq address="127.0.0.1" port="8080" check_script="/usr/local/bin/check_redis.py" interval="10s"
.ft P
.fi
.UNINDENT
@@ -122372,8 +130312,7 @@ CLI Example:
.sp
.nf
.ft C
-salt \(aq*\(aq consul.catalog_register node=\(aqnode1\(aq
- serviceid=\(aqredis_server1\(aq checkid=\(aqredis_check1\(aq
+salt \(aq*\(aq consul.catalog_register node=\(aqnode1\(aq serviceid=\(aqredis_server1\(aq checkid=\(aqredis_check1\(aq
.ft P
.fi
.UNINDENT
@@ -122494,9 +130433,7 @@ CLI Example:
.sp
.nf
.ft C
-salt \(aq*\(aq consul.catalog_register node=\(aqnode1\(aq address=\(aq192.168.1.1\(aq
- service=\(aqredis\(aq service_address=\(aq127.0.0.1\(aq service_port=\(aq8080\(aq
- service_id=\(aqredis_server1\(aq
+salt \(aq*\(aq consul.catalog_register node=\(aqnode1\(aq address=\(aq192.168.1.1\(aq service=\(aqredis\(aq service_address=\(aq127.0.0.1\(aq service_port=\(aq8080\(aq service_id=\(aqredis_server1\(aq
.ft P
.fi
.UNINDENT
@@ -122596,7 +130533,6 @@ CLI Example:
.nf
.ft C
salt \(aq*\(aq consul.delete key=\(aqweb\(aq
-
salt \(aq*\(aq consul.delete key=\(aqweb\(aq recurse=\(aqTrue\(aq
.ft P
.fi
@@ -122704,10 +130640,8 @@ CLI Example:
.nf
.ft C
salt \(aq*\(aq consul.get key=\(aqweb/key1\(aq
-
-salt \(aq*\(aq consul.list key=\(aqweb\(aq recurse=\(aqTrue
-
-salt \(aq*\(aq consul.list key=\(aqweb\(aq recurse=\(aqTrue\(aq decode=\(aqTrue\(aq
+salt \(aq*\(aq consul.get key=\(aqweb\(aq recurse=True
+salt \(aq*\(aq consul.get key=\(aqweb\(aq recurse=True decode=True
.ft P
.fi
.UNINDENT
@@ -122720,7 +130654,7 @@ decode option will show them as the decoded values.
.sp
.nf
.ft C
-salt \(aq*\(aq consul.list key=\(aqweb\(aq recurse=\(aqTrue\(aq decode=\(aqTrue\(aq raw=\(aqTrue\(aq
+salt \(aq*\(aq consul.get key=\(aqweb\(aq recurse=True decode=True raw=True
.ft P
.fi
.UNINDENT
@@ -122898,7 +130832,6 @@ CLI Example:
.nf
.ft C
salt \(aq*\(aq consul.list
-
salt \(aq*\(aq consul.list key=\(aqweb\(aq
.ft P
.fi
@@ -122946,11 +130879,9 @@ CLI Example:
.ft C
salt \(aq*\(aq consul.put key=\(aqweb/key1\(aq value="Hello there"
-salt \(aq*\(aq consul.put key=\(aqweb/key1\(aq value="Hello there"
- acquire=\(aqd5d371f4\-c380\-5280\-12fd\-8810be175592\(aq
+salt \(aq*\(aq consul.put key=\(aqweb/key1\(aq value="Hello there" acquire=\(aqd5d371f4\-c380\-5280\-12fd\-8810be175592\(aq
-salt \(aq*\(aq consul.put key=\(aqweb/key1\(aq value="Hello there"
- release=\(aqd5d371f4\-c380\-5280\-12fd\-8810be175592\(aq
+salt \(aq*\(aq consul.put key=\(aqweb/key1\(aq value="Hello there" release=\(aqd5d371f4\-c380\-5280\-12fd\-8810be175592\(aq
.ft P
.fi
.UNINDENT
@@ -123001,8 +130932,7 @@ CLI Example:
.sp
.nf
.ft C
-salt \(aq*\(aq consul.session_create node=\(aqnode1\(aq name=\(aqmy\-session\(aq
- behavior=\(aqdelete\(aq ttl=\(aq3600s\(aq
+salt \(aq*\(aq consul.session_create node=\(aqnode1\(aq name=\(aqmy\-session\(aq behavior=\(aqdelete\(aq ttl=\(aq3600s\(aq
.ft P
.fi
.UNINDENT
@@ -123837,6 +131767,11 @@ Manage Perl modules using CPAN
.sp
New in version 2015.5.0.
+.INDENT 0.0
+.TP
+.B salt.modules.cpan.__virtual__()
+Only work on supported POSIX\-like systems
+.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.cpan.install(module)
@@ -124191,6 +132126,11 @@ Linux
.UNINDENT
.INDENT 0.0
.TP
+.B salt.modules.csf.__virtual__()
+Only load if csf exists on the system
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.csf.allow(ip, port=None, proto=\(aqtcp\(aq, direction=\(aqin\(aq, port_origin=\(aqd\(aq, ip_origin=\(aqs\(aq, ttl=None, comment=\(aq\(aq)
Add an rule to csf allowed hosts
See \fB_access_rule()\fP\&.
@@ -124445,6 +132385,11 @@ Manage cygwin packages.
Module file to accompany the cyg state.
.INDENT 0.0
.TP
+.B salt.modules.cyg.__virtual__()
+Only works on Windows systems.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.cyg.check_valid_package(package, cyg_arch=\(aqx86_64\(aq, mirrors=None)
Check if the package is valid on the given mirrors.
.INDENT 7.0
@@ -124497,7 +132442,7 @@ CLI Example:
.nf
.ft C
salt \(aq*\(aq cyg.install dos2unix
-salt \(aq*\(aq cyg.install dos2unix mirrors=[{\(aqhttp://mirror\(aq: \(aqhttp://url/to/public/key}]
+salt \(aq*\(aq cyg.install dos2unix mirrors="[{\(aqhttp://mirror\(aq: \(aqhttp://url/to/public/key}]\(aq
.ft P
.fi
.UNINDENT
@@ -124552,7 +132497,7 @@ CLI Example:
.nf
.ft C
salt \(aq*\(aq cyg.uninstall dos2unix
-salt \(aq*\(aq cyg.uninstall dos2unix mirrors=[{\(aqhttp://mirror\(aq: \(aqhttp://url/to/public/key}]
+salt \(aq*\(aq cyg.uninstall dos2unix mirrors="[{\(aqhttp://mirror\(aq: \(aqhttp://url/to/public/key}]"
.ft P
.fi
.UNINDENT
@@ -124577,7 +132522,7 @@ CLI Example:
.nf
.ft C
salt \(aq*\(aq cyg.update
-salt \(aq*\(aq cyg.update dos2unix mirrors=[{\(aqhttp://mirror\(aq: \(aqhttp://url/to/public/key}]
+salt \(aq*\(aq cyg.update dos2unix mirrors="[{\(aqhttp://mirror\(aq: \(aqhttp://url/to/public/key}]"
.ft P
.fi
.UNINDENT
@@ -125081,6 +133026,11 @@ with an extra period in the file, similar to this:
.UNINDENT
.INDENT 0.0
.TP
+.B salt.modules.ddns.__virtual__()
+Confirm dnspython is available.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.ddns.add_host(zone, name, ttl, ip, nameserver=\(aq127.0.0.1\(aq, replace=True, timeout=5, port=53, **kwargs)
Add, replace, or update the A and PTR (reverse) records for a host.
.sp
@@ -125161,6 +133111,11 @@ separate file will allow them to load only on Debian\-based systems, while still
loading under the \fBapache\fP namespace.
.INDENT 0.0
.TP
+.B salt.modules.deb_apache.__virtual__()
+Only load the module if apache is installed
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.deb_apache.a2disconf(conf)
New in version 2016.3.0.
@@ -125357,6 +133312,11 @@ salt \(aq*\(aq apache.check_site_enabled example.com.conf
Module to provide Postgres compatibility to salt for debian family specific tools.
.INDENT 0.0
.TP
+.B salt.modules.deb_postgres.__virtual__()
+Only load this module if the pg_createcluster bin exists
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.deb_postgres.cluster_create(version, name=\(aqmain\(aq, port=None, locale=None, encoding=None, datadir=None)
Adds a cluster to the Postgres server.
.sp
@@ -125449,6 +133409,11 @@ environments. This also provides a function to generate debian repositories
This module implements the pkgbuild interface
.INDENT 0.0
.TP
+.B salt.modules.debbuild.__virtual__()
+Confirm this module is on a Debian based system, and has required utilities
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.debbuild.build(runas, tgt, dest_dir, spec, sources, deps, env, template, saltenv=\(aqbase\(aq, log_dir=\(aq/var/log/salt/pkgbuild\(aq)
Given the package destination directory, the tarball containing debian files (e.g. control)
and package sources, use pbuilder to safely build the platform package
@@ -125629,6 +133594,12 @@ This example command should build the libnacl SOURCE package and place it in
Support for Debconf
.INDENT 0.0
.TP
+.B salt.modules.debconfmod.__virtual__()
+Confirm this module is on a Debian based system and that debconf\-utils
+is installed.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.debconfmod.get_selections(fetchempty=True)
Answers to debconf questions for all packages in the following format:
.INDENT 7.0
@@ -125759,6 +133730,11 @@ References:
.UNINDENT
.INDENT 0.0
.TP
+.B salt.modules.debian_ip.__virtual__()
+Confine this module to Debian based distros
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.debian_ip.apply_network_settings(**settings)
Apply global network configuration.
.sp
@@ -125959,6 +133935,11 @@ minion, and it is using a different module (or gives an error similar to
.UNINDENT
.INDENT 0.0
.TP
+.B salt.modules.debian_service.__virtual__()
+Only work on Debian and when systemd isn\(aqt running
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.debian_service.available(name)
Returns \fBTrue\fP if the specified service is available, otherwise returns
\fBFalse\fP\&.
@@ -126422,6 +134403,11 @@ salt ns1 dig.TXT google.com
.UNINDENT
.INDENT 0.0
.TP
+.B salt.modules.dig.__virtual__()
+Only load module if dig binary is present
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.dig.check_ip(addr)
Check if address is a valid IP. returns True if valid, otherwise False.
.sp
@@ -126443,6 +134429,11 @@ salt ns1 dig.check_ip 1111:2222:3333:4444:5555:6666:7777:8888
Module for managing disks and blockdevices
.INDENT 0.0
.TP
+.B salt.modules.disk.__virtual__()
+Only work on POSIX\-like systems
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.disk.blkid(device=None)
Return block device attributes: UUID, LABEL, etc. This function only works
on systems where blkid is available.
@@ -126860,6 +134851,11 @@ salt \(aq*\(aq django.syncdb
Module for managing dnsmasq
.INDENT 0.0
.TP
+.B salt.modules.dnsmasq.__virtual__()
+Only work on POSIX\-like systems.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.dnsmasq.fullversion()
Shows installed version of dnsmasq and compile options.
.sp
@@ -127075,6 +135071,12 @@ salt ns1 dnsutil.SPF google.com
.UNINDENT
.INDENT 0.0
.TP
+.B salt.modules.dnsutil.__virtual__()
+Generic, should work on any platform (including Windows). Functionality
+which requires dependencies outside of Python do not belong in this module.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.dnsutil.check_ip(ip_addr)
Check that string ip_addr is a valid IP
.sp
@@ -127254,10 +135256,10 @@ docker\-compose.yml will be stored and the content of this latter:
.nf
.ft C
# salt\-call \-l debug dockercompose.create /tmp/toto \(aq
- database:
- image: mongo:3.0
- command: mongod \-\-smallfiles \-\-quiet \-\-logpath=/dev/null
- \(aq
+database:
+image: mongo:3.0
+command: mongod \-\-smallfiles \-\-quiet \-\-logpath=/dev/null
+\(aq
.ft P
.fi
.UNINDENT
@@ -127927,6 +135929,11 @@ This execution module provides functions that shadow those from the \fBcmd\fP mo
.SS Detailed Function Documentation
.INDENT 0.0
.TP
+.B salt.modules.dockermod.__virtual__()
+Only load if docker libs are present
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.dockermod.build(path=None, image=None, cache=True, rm=True, api_response=False, fileobj=None, dockerfile=None, buildargs=None)
Builds a docker image from a Dockerfile or a URL
.INDENT 7.0
@@ -128797,23 +136804,11 @@ Config options for the \fBlog_driver\fP config option. Requires Docker
Example:
.INDENT 7.0
.IP \(bu 2
-
-.nf
-\(ga\(ga
-.fi
-log_opt="syslog\-address=tcp://192.168.0.42,syslog\-facility=daemon"
+\fBlog_opt="syslog\-address=tcp://192.168.0.42,syslog\-facility=daemon"\fP
.IP \(bu 2
-
-.nf
-\(ga\(ga
-.fi
-log_opt="[\(aqsyslog\-address=tcp://192.168.0.42\(aq, \(aqsyslog\-facility=daemon\(aq]"
+\fBlog_opt="[\(aqsyslog\-address=tcp://192.168.0.42\(aq, \(aqsyslog\-facility=daemon\(aq]"\fP
.IP \(bu 2
-
-.nf
-\(ga\(ga
-.fi
-log_opt="{\(aqsyslog\-address\(aq: \(aq\fI\%tcp://192.168.0.42\fP\(aq, \(aqsyslog\-facility: daemon
+\fBlog_opt="{\(aqsyslog\-address\(aq: \(aqtcp://192.168.0.42\(aq, \(aqsyslog\-facility\(aq: \(aqdaemon\(aq}"\fP
.UNINDENT
.TP
.B lxc_conf
@@ -131659,6 +139654,11 @@ salt myminion docker.wait mycontainer
Support for DEB packages
.INDENT 0.0
.TP
+.B salt.modules.dpkg.__virtual__()
+Confirm this module is on a Debian based system
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.dpkg.bin_pkg_info(path, saltenv=\(aqbase\(aq)
New in version 2015.8.0.
@@ -133141,6 +141141,11 @@ salt \(aq*\(aq drbd.overview
Package support for the dummy proxy used by the test suite
.INDENT 0.0
.TP
+.B salt.modules.dummyproxy_package.__virtual__()
+Only work on systems that are a proxy minion
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.dummyproxy_package.install(name=None, refresh=False, fromrepo=None, pkgs=None, sources=None, **kwargs)
.UNINDENT
.INDENT 0.0
@@ -133184,6 +141189,11 @@ salt \(aq*\(aq pkg.version ...
Provide the service module for the dummy proxy used in integration tests
.INDENT 0.0
.TP
+.B salt.modules.dummyproxy_service.__virtual__()
+Only work on systems that are a proxy minion
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.dummyproxy_service.enabled(name, sig=None)
Only the \(aqredbull\(aq service is \(aqenabled\(aq in the test
.sp
@@ -133344,6 +141354,11 @@ For now all package names \fIMUST\fP include the package category,
i.e. \fB\(aqvim\(aq\fP will not work, \fB\(aqapp\-editors/vim\(aq\fP will.
.INDENT 0.0
.TP
+.B salt.modules.ebuild.__virtual__()
+Confirm this module is on a Gentoo based system
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.ebuild.check_db(*names, **kwargs)
New in version 0.17.0.
@@ -134009,6 +142024,11 @@ salt \(aq*\(aq pkg.version_cmp \(aq0.2.4\-0\(aq \(aq0.2.4.1\-0\(aq
Support for Eix
.INDENT 0.0
.TP
+.B salt.modules.eix.__virtual__()
+Only work on Gentoo systems with eix installed
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.eix.sync()
Sync portage/overlay trees and update the eix database
.sp
@@ -134103,6 +142123,11 @@ Some functionality might be limited by elasticsearch\-py and Elasticsearch serve
.UNINDENT
.INDENT 0.0
.TP
+.B salt.modules.elasticsearch.__virtual__()
+Only load if elasticsearch libraries exist.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.elasticsearch.alias_create(indices, alias, hosts=None, body=None, profile=None)
Create an alias for a specific index/indices
.INDENT 7.0
@@ -135230,6 +143255,11 @@ Support for getting and setting the environment variables
of the current salt process.
.INDENT 0.0
.TP
+.B salt.modules.environ.__virtual__()
+No dependency checks, and not renaming, just return True
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.environ.get(key, default=\(aq\(aq)
Get a single salt process environment variable.
.INDENT 7.0
@@ -135434,6 +143464,11 @@ salt \(aq*\(aq environ.setval baz bar permanent=HKLM
Support for eselect, Gentoo\(aqs configuration and management tool.
.INDENT 0.0
.TP
+.B salt.modules.eselect.__virtual__()
+Only work on Gentoo systems with eselect installed
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.eselect.exec_action(module, action, module_parameter=None, action_parameter=None, state_only=False)
Execute an arbitrary action on a module.
.INDENT 7.0
@@ -135627,6 +143662,11 @@ salt \(aqexsi\-proxy\(aq esxi.cmd get_service_policy service_name=\(aqssh\(aq
.fi
.UNINDENT
.UNINDENT
+.INDENT 0.0
+.TP
+.B salt.modules.esxi.__virtual__()
+Only work on proxy
+.UNINDENT
.SS salt.modules.etcd_mod
.sp
Execution module to work with etcd
@@ -135684,6 +143724,11 @@ pillars.
.UNINDENT
.INDENT 0.0
.TP
+.B salt.modules.etcd_mod.__virtual__()
+Only return if python\-etcd is installed
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.etcd_mod.get(key, recurse=False, profile=None)
New in version 2014.7.0.
@@ -135913,6 +143958,11 @@ linux
.UNINDENT
.INDENT 0.0
.TP
+.B salt.modules.ethtool.__virtual__()
+Only load this module if python\-ethtool is installed
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.ethtool.set_coalesce(devname, **kwargs)
Changes the coalescing settings of the specified network device
.sp
@@ -136169,6 +144219,11 @@ sudo \-E salt\-call event.send myco/jenkins/build/success with_env=[BUILD_ID, BU
Module for managing ext2/3/4 file systems
.INDENT 0.0
.TP
+.B salt.modules.extfs.__virtual__()
+Only work on POSIX\-like systems
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.extfs.attributes(device, args=None)
Return attributes from dumpe2fs for a specified device
.sp
@@ -136364,6 +144419,11 @@ and special files on the minion, set/read user,
group, mode, and data
.INDENT 0.0
.TP
+.B salt.modules.file.__virtual__()
+Only work on POSIX\-like systems
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.file.access(path, mode)
New in version 2014.1.0.
@@ -138312,7 +146372,7 @@ default structure.
.B source
file reference on the master
.TP
-.B source_hash
+.B source_sum
sum hash for source
.TP
.B user
@@ -138940,7 +147000,8 @@ positive integer \fBn\fP, only \fBn\fP occurrences will be replaced,
otherwise all occurrences will be replaced.
.TP
.B flags (list or int)
-A list of flags defined in the \fI\%re module documentation\fP\&. Each list item should be a string that will
+A list of flags defined in the \fBre\fP module documentation from the
+Python standard library. Each list item should be a string that will
correlate to the human\-friendly flag name. E.g., \fB[\(aqIGNORECASE\(aq,
\(aqMULTILINE\(aq]\fP\&. Optionally, \fBflags\fP may be an int, with a value
corresponding to the XOR (\fB|\fP) of all the desired flags. Defaults to
@@ -139635,6 +147696,11 @@ Support for firewalld.
.sp
New in version 2015.2.0.
+.INDENT 0.0
+.TP
+.B salt.modules.firewalld.__virtual__()
+Check to see if firewall\-cmd exists
+.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.firewalld.add_interface(zone, interface, permanent=True)
@@ -140602,6 +148668,11 @@ salt \(aq*\(aq firewalld.version
Module for viewing and modifying sysctl parameters
.INDENT 0.0
.TP
+.B salt.modules.freebsd_sysctl.__virtual__()
+Only runs on FreeBSD systems
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.freebsd_sysctl.assign(name, value)
Assign a single sysctl parameter for this minion
.sp
@@ -140688,6 +148759,14 @@ FreeBSD
.UNINDENT
.INDENT 0.0
.TP
+.B salt.modules.freebsd_update.__virtual__()
+New in version 2016.3.4.
+
+.sp
+Only work on FreeBSD RELEASEs >= 6.2, where freebsd\-update was introduced.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.freebsd_update.fetch(**kwargs)
New in version 2016.3.4.
@@ -140784,6 +148863,11 @@ Parameters of freebsd\-update command.
The jail module for FreeBSD
.INDENT 0.0
.TP
+.B salt.modules.freebsdjail.__virtual__()
+Only runs on FreeBSD systems
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.freebsdjail.fstab(jail)
Display contents of a fstab(5) file defined in specified
jail\(aqs configuration. If no file is defined, return False.
@@ -140941,6 +149025,11 @@ salt \(aq*\(aq jail.sysctl
Module to manage FreeBSD kernel modules
.INDENT 0.0
.TP
+.B salt.modules.freebsdkmod.__virtual__()
+Only runs on FreeBSD systems
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.freebsdkmod.available()
Return a list of all available kernel modules
.sp
@@ -141170,6 +149259,13 @@ recognized, and override their config counterparts from section 1 above.
.UNINDENT
.INDENT 0.0
.TP
+.B salt.modules.freebsdpkg.__virtual__()
+Load as \(aqpkg\(aq on FreeBSD versions less than 10.
+Don\(aqt load on FreeBSD 9 when the config option
+\fBproviders:pkg\fP is set to \(aqpkgng\(aq.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.freebsdpkg.file_dict(*packages)
List the files that belong to a package, grouped by package. Not
specifying any packages will return a list of _every_ file on the
@@ -141458,6 +149554,11 @@ salt minion\-id ports.install security/nmap
.UNINDENT
.INDENT 0.0
.TP
+.B salt.modules.freebsdports.__virtual__()
+Only runs on FreeBSD systems
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.freebsdports.config(name, reset=False, **kwargs)
Modify configuration options for a given port. Multiple options can be
specified. To see the available options for a port, use
@@ -141678,6 +149779,11 @@ minion, and it is using a different module (or gives an error similar to
.UNINDENT
.INDENT 0.0
.TP
+.B salt.modules.freebsdservice.__virtual__()
+Only work on FreeBSD
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.freebsdservice.available(name, jail=None)
Check that the given service is available.
.sp
@@ -142373,6 +150479,12 @@ Module for managing container and VM images
.sp
New in version 2014.7.0.
+.INDENT 0.0
+.TP
+.B salt.modules.genesis.__virtual__()
+By default, this will be available on all platforms; but not all distros
+will necessarily be supported
+.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.genesis.avail_platforms()
@@ -142564,6 +150676,11 @@ minion, and it is using a different module (or gives an error similar to
.UNINDENT
.INDENT 0.0
.TP
+.B salt.modules.gentoo_service.__virtual__()
+Only work on systems which default to OpenRC
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.gentoo_service.available(name)
Returns \fBTrue\fP if the specified service is available, otherwise returns
\fBFalse\fP\&.
@@ -142830,6 +150947,11 @@ salt \(aq*\(aq service.zap
Support for Gentoolkit
.INDENT 0.0
.TP
+.B salt.modules.gentoolkitmod.__virtual__()
+Only work on Gentoo systems with gentoolkit installed
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.gentoolkitmod.eclean_dist(destructive=False, package_names=False, size_limit=0, time_limit=0, fetch_restricted=False, exclude_file=\(aq/etc/eclean/distfiles.exclude\(aq)
Clean obsolete portage sources
.INDENT 7.0
@@ -143005,6 +151127,11 @@ salt \(aq*\(aq gentoolkit.revdep_rebuild
Support for the Git SCM
.INDENT 0.0
.TP
+.B salt.modules.git.__virtual__()
+Only load if git exists on the system
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.git.add(cwd, filename, opts=\(aq\(aq, git_opts=\(aq\(aq, user=None, password=None, ignore_retcode=False)
Changed in version 2015.8.0: The \fB\-\-verbose\fP command line argument is now implied
@@ -146551,6 +154678,11 @@ github:
.UNINDENT
.INDENT 0.0
.TP
+.B salt.modules.github.__virtual__()
+Only load this module if PyGithub is installed on this minion.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.github.add_repo(name, description=None, homepage=None, private=None, has_issues=None, has_wiki=None, has_downloads=None, auto_init=None, gitignore_template=None, license_template=None, profile=\(aqgithub\(aq)
Create a new github repository.
.INDENT 7.0
@@ -147737,6 +155869,12 @@ salt \(aq*\(aq glance.image_list profile=openstack1
.UNINDENT
.INDENT 0.0
.TP
+.B salt.modules.glance.__virtual__()
+Only load this module if glance
+is installed on this minion.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.glance.image_create(name, location=None, profile=None, visibility=None, container_format=\(aqbare\(aq, disk_format=\(aqraw\(aq, protected=None)
Create an image (glance image\-create)
.sp
@@ -147896,6 +156034,11 @@ salt \(aq*\(aq glance.schema_get name=f16\-jeos
Manage a glusterfs pool
.INDENT 0.0
.TP
+.B salt.modules.glusterfs.__virtual__()
+Only load this module if the gluster command exists
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.glusterfs.add_volume_bricks(name, bricks)
Add brick(s) to an existing volume
.INDENT 7.0
@@ -147906,11 +156049,23 @@ Volume name
.B bricks
List of bricks to add to the volume
.UNINDENT
+.sp
+CLI Example:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+salt \(aq*\(aq glusterfs.add_volume_bricks
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.glusterfs.create_volume(name, bricks, stripe=False, replica=False, device_vg=False, transport=\(aqtcp\(aq, start=False, force=False)
-Create a glusterfs volume.
+Create a glusterfs volume
.INDENT 7.0
.TP
.B name
@@ -147938,7 +156093,7 @@ Start the volume after creation
Force volume creation, this works even if creating in root FS
.UNINDENT
.sp
-CLI Example:
+CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
@@ -147962,7 +156117,20 @@ Deletes a gluster volume
Volume to delete
.TP
.B stop
-Stop volume before delete if it is started, True by default
+True
+If \fBTrue\fP, stop volume before delete
+.UNINDENT
+.sp
+CLI Example:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+salt \(aq*\(aq glusterfs.delete_volume
+.ft P
+.fi
+.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
@@ -147974,6 +156142,18 @@ Disable quota on a glusterfs volume.
.B name
Name of the gluster volume
.UNINDENT
+.sp
+CLI Example:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+salt \(aq*\(aq glusterfs.disable_quota_volume
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
@@ -147984,6 +156164,18 @@ Enable quota on a glusterfs volume.
.B name
Name of the gluster volume
.UNINDENT
+.sp
+CLI Example:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+salt \(aq*\(aq glusterfs.enable_quota_volume
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
@@ -148013,11 +156205,22 @@ salt \(aq*\(aq glusterfs.info
.INDENT 0.0
.TP
.B salt.modules.glusterfs.list_quota_volume(name)
-List quotas of glusterfs volume.
-name
+List quotas of glusterfs volume
+.INDENT 7.0
+.TP
+.B name
+Name of the gluster volume
+.UNINDENT
+.sp
+CLI Example:
.INDENT 7.0
.INDENT 3.5
-Name of the gluster volume
+.sp
+.nf
+.ft C
+salt \(aq*\(aq glusterfs.list_quota_volume
+.ft P
+.fi
.UNINDENT
.UNINDENT
.UNINDENT
@@ -148158,7 +156361,7 @@ salt \(aq*\(aq glusterfs.set_quota_volume enable_quota=Tr
.INDENT 0.0
.TP
.B salt.modules.glusterfs.start_volume(name, force=False)
-Start a gluster volume.
+Start a gluster volume
.INDENT 7.0
.TP
.B name
@@ -148206,7 +156409,7 @@ salt \(aq*\(aq glusterfs.status myvolume
.INDENT 0.0
.TP
.B salt.modules.glusterfs.stop_volume(name, force=False)
-Stop a gluster volume.
+Stop a gluster volume
.INDENT 7.0
.TP
.B name
@@ -148214,7 +156417,9 @@ Volume name
.TP
.B force
Force stop the volume
-.. versionadded:: 2015.8.4
+.sp
+New in version 2015.8.4.
+
.UNINDENT
.sp
CLI Example:
@@ -148232,24 +156437,25 @@ salt \(aq*\(aq glusterfs.stop_volume mycluster
.INDENT 0.0
.TP
.B salt.modules.glusterfs.unset_quota_volume(name, path)
-Unset quota to glusterfs volume.
-name
+Unset quota on glusterfs volume
.INDENT 7.0
-.INDENT 3.5
+.TP
+.B name
Name of the gluster volume
-.UNINDENT
-.UNINDENT
-.INDENT 7.0
.TP
.B path
Folder path for restriction in volume
.UNINDENT
.sp
CLI Example:
-.. code\-block:: bash
.INDENT 7.0
.INDENT 3.5
+.sp
+.nf
+.ft C
salt \(aq*\(aq glusterfs.unset_quota_volume
+.ft P
+.fi
.UNINDENT
.UNINDENT
.UNINDENT
@@ -148258,6 +156464,11 @@ salt \(aq*\(aq glusterfs.unset_quota_volume
GNOME implementations
.INDENT 0.0
.TP
+.B salt.modules.gnomedesktop.__virtual__()
+Only load if the Gio and Glib modules are available
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.gnomedesktop.get(schema=None, key=None, user=None, **kwargs)
Get key in a particular GNOME schema
.sp
@@ -148460,6 +156671,11 @@ installed.
.UNINDENT
.INDENT 0.0
.TP
+.B salt.modules.gpg.__virtual__()
+Makes sure that python\-gnupg and gpg are available.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.gpg.create_key(*args, **kwargs)
Create a key in the GPG keychain
.sp
@@ -149105,6 +157321,11 @@ grafana:
.UNINDENT
.INDENT 0.0
.TP
+.B salt.modules.grafana4.__virtual__()
+Only load if requests is installed
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.grafana4.create_datasource(orgname=None, profile=\(aqgrafana\(aq, **kwargs)
Create a new datasource in an organisation.
.INDENT 7.0
@@ -150205,6 +158426,16 @@ The grain key from which to delete the value.
.UNINDENT
.sp
CLI Example:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+salt \(aq*\(aq grains.delkey key
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
@@ -150858,6 +159089,11 @@ minion, and it is using a different module (or gives an error similar to
.UNINDENT
.INDENT 0.0
.TP
+.B salt.modules.groupadd.__virtual__()
+Set the user module if the kernel is Linux or OpenBSD
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.groupadd.add(name, gid=None, system=False, root=None)
Add the specified group
.sp
@@ -151003,6 +159239,11 @@ foo:x:1234:user1,user2,user3,...
Support for GRUB Legacy
.INDENT 0.0
.TP
+.B salt.modules.grub_legacy.__virtual__()
+Only load the module if grub is installed
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.grub_legacy.conf()
Parse GRUB conf file
.sp
@@ -151048,6 +159289,11 @@ libguestfs
.UNINDENT
.INDENT 0.0
.TP
+.B salt.modules.guestfs.__virtual__()
+Only load if libguestfs python bindings are installed
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.guestfs.mount(location, access=\(aqrw\(aq, root=None)
Mount an image
.sp
@@ -151081,6 +159327,11 @@ linux
.UNINDENT
.INDENT 0.0
.TP
+.B salt.modules.hadoop.__virtual__()
+Check if hadoop is present, then load the module
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.hadoop.dfs(command=None, *args)
Execute a command on DFS
.sp
@@ -151172,6 +159423,11 @@ Support for haproxy
.sp
New in version 2014.7.0.
+.INDENT 0.0
+.TP
+.B salt.modules.haproxyconn.__virtual__()
+Only load the module if haproxyctl is installed
+.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.haproxyconn.disable_server(name, backend, socket=\(aq/var/run/haproxy.sock\(aq)
@@ -151805,6 +160061,12 @@ salt \(aq*\(aq heat.flavor_list profile=openstack1
.UNINDENT
.INDENT 0.0
.TP
+.B salt.modules.heat.__virtual__()
+Only load this module if heat
+is installed on this minion.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.heat.create_stack(name=None, template_file=None, environment=None, parameters=None, poll=0, rollback=False, timeout=60, profile=None, enviroment=None)
Create a stack (heat stack\-create)
.INDENT 7.0
@@ -152016,6 +160278,11 @@ be removed in Salt Neon.
Support for the Mercurial SCM
.INDENT 0.0
.TP
+.B salt.modules.hg.__virtual__()
+Only load if hg is installed
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.hg.archive(cwd, output, rev=\(aqtip\(aq, fmt=None, prefix=None, user=None)
Export a tarball from the repository
.INDENT 7.0
@@ -152309,6 +160576,16 @@ hipchat:
.UNINDENT
.INDENT 0.0
.TP
+.B salt.modules.hipchat.__virtual__()
+Return virtual name of the module.
+.INDENT 7.0
+.TP
+.B Returns
+The virtual name of the module.
+.UNINDENT
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.hipchat.find_room(name, api_url=None, api_key=None, api_version=None)
Find a room by name and return it.
.INDENT 7.0
@@ -152645,6 +160922,11 @@ The functions here will load inside the webutil module. This allows other
functions that don\(aqt use htpasswd to use the webutil module name.
.INDENT 0.0
.TP
+.B salt.modules.htpasswd.__virtual__()
+Only load the module if htpasswd is installed
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.htpasswd.useradd(pwfile, user, password, opts=\(aq\(aq, runas=None)
Add a user to htpasswd file using the htpasswd command. If the htpasswd
file does not exist, it will be created.
@@ -152879,6 +161161,11 @@ New in version 2015.8.0.
Requires an \fBapi_key\fP in \fB/etc/salt/minion\fP:
.INDENT 0.0
.TP
+.B salt.modules.ifttt.__virtual__()
+Only load the module if apache is installed
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.ifttt.trigger_event(event=None, **kwargs)
Trigger a configured event in IFTTT.
.INDENT 7.0
@@ -152900,6 +161187,11 @@ hponcfg (SmartStart Scripting Toolkit Linux Edition)
.UNINDENT
.INDENT 0.0
.TP
+.B salt.modules.ilo.__virtual__()
+Make sure hponcfg tool is accessible
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.ilo.change_password(username, password)
Reset a users password
.sp
@@ -153278,6 +161570,11 @@ icinga2 server
.UNINDENT
.INDENT 0.0
.TP
+.B salt.modules.icinga2.__virtual__()
+Only load this module if the mysql libraries exist
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.icinga2.generate_cert(domain)
Generate an icinga2 client certificate and key.
.INDENT 7.0
@@ -153607,6 +161904,11 @@ would override \fBuser\fP and \fBpassword\fP while still using the defaults for
.UNINDENT
.INDENT 0.0
.TP
+.B salt.modules.influx.__virtual__()
+Only load if influxdb lib is present
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.influx.alter_retention_policy(database, name, duration, replication, default=False, **client_args)
Modify an existing retention policy.
.INDENT 7.0
@@ -154257,6 +162559,11 @@ overwrite options passed into pillar.
.UNINDENT
.INDENT 0.0
.TP
+.B salt.modules.influx08.__virtual__()
+Only load if influxdb lib is present
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.influx08.db_create(name, user=None, password=None, host=None, port=None)
Create a database
.INDENT 7.0
@@ -155068,6 +163375,11 @@ all
(for example /etc/sysctl.conf)
.INDENT 0.0
.TP
+.B salt.modules.ini_manage.__virtual__()
+Rename to ini
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.ini_manage.get_option(file_name, section, option, separator=\(aq=\(aq)
Get value of a key from a section in an ini file. Returns \fBNone\fP if
no matching key was found.
@@ -155274,6 +163586,19 @@ the inspected data. This database can be destroyed or corrupted, so it should
be simply re\-created from scratch.
.INDENT 7.0
.TP
+.B __getattr__(item)
+Proxy methods from the Database instance.
+.INDENT 7.0
+.TP
+.B Parameters
+\fBitem\fP \-\-
+.TP
+.B Returns
+
+.UNINDENT
+.UNINDENT
+.INDENT 7.0
+.TP
.B close()
Close the database connection.
.UNINDENT
@@ -155321,6 +163646,24 @@ System information exception.
Query the system.
This class is actually puts all Salt features together,
so there would be no need to pick it from various places.
+.INDENT 7.0
+.TP
+.B __call__(*args, **kwargs)
+Call the query with the defined scope.
+.INDENT 7.0
+.TP
+.B Parameters
+.INDENT 7.0
+.IP \(bu 2
+\fBargs\fP \-\-
+.IP \(bu 2
+\fBkwargs\fP \-\-
+.UNINDENT
+.TP
+.B Returns
+
+.UNINDENT
+.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
@@ -155363,11 +163706,7 @@ Payload file.
.INDENT 0.0
.TP
.B codeauthor
-
-.nf
-:email:\(gaBo Maryniuk \(ga
-.fi
-
+Bo Maryniuk <\fI\%bo@suse.de\fP>
.UNINDENT
.INDENT 0.0
.TP
@@ -155606,6 +163945,11 @@ Load data by keys.
Module for full system inspection.
.INDENT 0.0
.TP
+.B salt.modules.inspector.__virtual__()
+Only work on POSIX\-like systems
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.inspector.build(format=\(aqqcow2\(aq, path=\(aq/tmp/\(aq)
Build an image from a current system description.
The image is a system image can be output in bootable ISO or QCOW2 formats.
@@ -155665,7 +164009,7 @@ Parameters:
.IP \(bu 2
.INDENT 2.0
.TP
-\fBpath\fP: If \fIlocal=True\fP, then specifies the path where file with the Kiwi description is written.
+.B \fBpath\fP: If \fIlocal=True\fP, then specifies the path where file with the Kiwi description is written.
Default: \fI/tmp\fP\&.
.UNINDENT
.UNINDENT
@@ -155739,7 +164083,7 @@ Parameters:
.IP \(bu 2
.INDENT 2.0
.TP
-\fBIdentity\fP: Return user accounts information for this system.
+.B \fBIdentity\fP: Return user accounts information for this system.
.INDENT 7.0
.TP
.B accounts
@@ -155754,7 +164098,7 @@ True (or False, default) to return only disabled accounts.
.IP \(bu 2
.INDENT 2.0
.TP
-\fBpayload\fP: Payload scope parameters:
+.B \fBpayload\fP: Payload scope parameters:
.INDENT 7.0
.TP
.B filter
@@ -156071,11 +164415,12 @@ api_kg=None
.UNINDENT
.UNINDENT
+.sp
+Return Data
.INDENT 7.0
-.TP
-.B return
+.INDENT 3.5
A Python dict with the following keys/values:
-.INDENT 7.0
+.INDENT 0.0
.INDENT 3.5
.sp
.nf
@@ -156103,6 +164448,7 @@ A Python dict with the following keys/values:
.UNINDENT
.UNINDENT
.UNINDENT
+.UNINDENT
.sp
CLI Examples:
.INDENT 7.0
@@ -156144,8 +164490,8 @@ api_kg=None
.UNINDENT
.INDENT 7.0
.TP
-.B return
-channel session supports:
+.B Return Data
+channel session supports
.INDENT 7.0
.INDENT 3.5
.sp
@@ -156359,11 +164705,9 @@ api_kg=None
.UNINDENT
.UNINDENT
.sp
-return
+Return Data
.INDENT 7.0
.INDENT 3.5
-.INDENT 0.0
-.INDENT 3.5
.sp
.nf
.ft C
@@ -156380,8 +164724,6 @@ access:
.fi
.UNINDENT
.UNINDENT
-.UNINDENT
-.UNINDENT
.sp
CLI Examples:
.INDENT 7.0
@@ -156424,11 +164766,9 @@ api_kg=None
.UNINDENT
.UNINDENT
.sp
-return
+Return Data
.INDENT 7.0
.INDENT 3.5
-.INDENT 0.0
-.INDENT 3.5
.sp
.nf
.ft C
@@ -156446,8 +164786,6 @@ access:
.fi
.UNINDENT
.UNINDENT
-.UNINDENT
-.UNINDENT
.sp
CLI Examples:
.INDENT 7.0
@@ -156709,24 +165047,22 @@ Set channel access
.UNINDENT
.IP \(bu 2
-\fBalerting\fP \-\- .INDENT 2.0
-.TP
-.B PEF Alerting Enable/Disable
-.INDENT 7.0
+\fBalerting\fP \-\-
+.sp
+PEF Alerting Enable/Disable
+.INDENT 2.0
.IP \(bu 2
True = enable PEF Alerting
.IP \(bu 2
False = disable PEF Alerting on this channel
-.UNINDENT
-.sp
(Alert Immediate command can still be used to generate alerts)
.UNINDENT
.IP \(bu 2
-\fBper_msg_auth\fP \-\- .INDENT 2.0
-.TP
-.B Per\-message Authentication
-.INDENT 7.0
+\fBper_msg_auth\fP \-\-
+.sp
+Per\-message Authentication
+.INDENT 2.0
.IP \(bu 2
True = enable
.IP \(bu 2
@@ -156734,13 +165070,12 @@ False = disable Per\-message Authentication. [Authentication required to
activate any session on this channel, but authentication not
used on subsequent packets for the session.]
.UNINDENT
-.UNINDENT
.IP \(bu 2
-\fBuser_level_auth\fP \-\- .INDENT 2.0
-.TP
-.B User Level Authentication Enable/Disable.
-.INDENT 7.0
+\fBuser_level_auth\fP \-\-
+.sp
+User Level Authentication Enable/Disable
+.INDENT 2.0
.IP \(bu 2
True = enable User Level Authentication. All User Level commands are
to be authenticated per the Authentication Type that was
@@ -156754,16 +165089,13 @@ set to None if they contain user level commands.
For outgoing packets, the BMC returns responses with the same
Authentication Type that was used for the request.
.UNINDENT
-.UNINDENT
.IP \(bu 2
\fBaccess_mode\fP \-\-
.sp
-Access Mode for IPMI messaging
-(PEF Alerting is enabled/disabled separately from IPMI messaging)
+Access Mode for IPMI messaging (PEF Alerting is enabled/disabled
+separately from IPMI messaging)
.INDENT 2.0
-.INDENT 3.5
-.INDENT 0.0
.IP \(bu 2
disabled = disabled for IPMI messaging
.IP \(bu 2
@@ -156776,18 +165108,13 @@ BIOS typically dedicates the serial connection to the BMC.
shared = same as always available, but BIOS typically leaves the
serial port available for software use.
.UNINDENT
-.UNINDENT
-.UNINDENT
.IP \(bu 2
\fBprivilege_update_mode\fP \-\-
.sp
-Channel Privilege Level Limit.
-This value sets the maximum privilege level
-that can be accepted on the specified channel.
+Channel Privilege Level Limit. This value sets the maximum privilege
+level that can be accepted on the specified channel.
.INDENT 2.0
-.INDENT 3.5
-.INDENT 0.0
.IP \(bu 2
dont_change = don\(aqt set or change channel Privilege Level Limit
.IP \(bu 2
@@ -156795,14 +165122,12 @@ non_volatile = non\-volatile Privilege Level Limit according
.IP \(bu 2
volatile = volatile setting of Privilege Level Limit
.UNINDENT
-.UNINDENT
-.UNINDENT
.IP \(bu 2
-\fBprivilege_level\fP \-\- .INDENT 2.0
-.TP
-.B Channel Privilege Level Limit
-.INDENT 7.0
+\fBprivilege_level\fP \-\-
+.sp
+Channel Privilege Level Limit
+.INDENT 2.0
.IP \(bu 2
reserved = unused
.IP \(bu 2
@@ -156816,7 +165141,6 @@ administrator
.IP \(bu 2
proprietary = used by OEM
.UNINDENT
-.UNINDENT
.IP \(bu 2
\fBkwargs\fP \-\- .INDENT 2.0
@@ -156964,10 +165288,10 @@ Set user access
.IP \(bu 2
\fBchannel\fP \-\- number [1:7]
.IP \(bu 2
-\fBcallback\fP \-\- .INDENT 2.0
-.TP
-.B User Restricted to Callback
-.INDENT 7.0
+\fBcallback\fP \-\-
+.sp
+User Restricted to Callback
+.INDENT 2.0
.IP \(bu 2
False = User Privilege Limit is determined by the User Privilege Limit
parameter, below, for both callback and non\-callback connections.
@@ -156979,18 +165303,15 @@ a Callback when they \(aqcall in\(aq to the BMC, but once the callback
connection has been made, the user could potentially establish a
session as an Operator.
.UNINDENT
-.UNINDENT
.IP \(bu 2
-\fBlink_auth\fP \-\- User Link authentication
-enable/disable (used to enable whether this
-user\(aqs name and password information will be used for link
+\fBlink_auth\fP \-\- User Link authentication enable/disable (used to enable
+whether this user\(aqs name and password information will be used for link
authentication, e.g. PPP CHAP) for the given channel. Link
authentication itself is a global setting for the channel and is
enabled/disabled via the serial/modem configuration parameters.
.IP \(bu 2
-\fBipmi_msg\fP \-\- User IPMI Messaging:
-(used to enable/disable whether
+\fBipmi_msg\fP \-\- User IPMI Messaging: (used to enable/disable whether
this user\(aqs name and password information will be used for IPMI
Messaging. In this case, \(aqIPMI Messaging\(aq refers to the ability to
execute generic IPMI commands that are not associated with a
@@ -157006,8 +165327,6 @@ unavailable.)
User Privilege Limit. (Determines the maximum privilege level that the
user is allowed to switch to on the specified channel.)
.INDENT 2.0
-.INDENT 3.5
-.INDENT 0.0
.IP \(bu 2
callback
.IP \(bu 2
@@ -157021,8 +165340,6 @@ proprietary
.IP \(bu 2
no_access
.UNINDENT
-.UNINDENT
-.UNINDENT
.IP \(bu 2
\fBkwargs\fP \-\- .INDENT 2.0
@@ -157200,6 +165517,11 @@ salt\-call ipmi.user_delete uid=2
Support for ipset
.INDENT 0.0
.TP
+.B salt.modules.ipset.__virtual__()
+Only load the module if ipset is installed
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.ipset.add(set=None, entry=None, family=\(aqipv4\(aq, **kwargs)
Append an entry to the specified set.
.sp
@@ -157453,35 +165775,36 @@ salt \(aq*\(aq ipset.version
Support for iptables
.SS Configuration Options
.sp
-The following options can be set in the minion config, minion grains
-, minion pillar, or
-\fImaster config\fP\&.
+The following options can be set in the minion config, grains, pillar, or
+master config. The configuration is read using \fBconfig.get\fP\&.
.INDENT 0.0
.IP \(bu 2
\fBiptables.save_filters\fP: List of REGEX strings to FILTER OUT matching lines
-.INDENT 2.0
-.INDENT 3.5
-This is useful for filtering out chains, rules, etc that you do not
-wish to persist, such as ephemeral Docker rules.
+.sp
+This is useful for filtering out chains, rules, etc that you do not wish to
+persist, such as ephemeral Docker rules.
.sp
The default is to not filter out anything.
-.INDENT 0.0
+.INDENT 2.0
.INDENT 3.5
.sp
.nf
.ft C
iptables.save_filters:
- \- "\-j CATTLE_PREROUTING"
- \- "\-j DOCKER"
- \- "\-A POSTROUTING"
- \- "\-A CATTLE_POSTROUTING"
- \- "\-A FORWARD"
+ \- "\-j CATTLE_PREROUTING"
+ \- "\-j DOCKER"
+ \- "\-A POSTROUTING"
+ \- "\-A CATTLE_POSTROUTING"
+ \- "\-A FORWARD"
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
-.UNINDENT
+.INDENT 0.0
+.TP
+.B salt.modules.iptables.__virtual__()
+Only load the module if iptables is installed
.UNINDENT
.INDENT 0.0
.TP
@@ -157918,6 +166241,11 @@ salt \(aq*\(aq iptables.version family=ipv6
Support for Wireless Tools for Linux
.INDENT 0.0
.TP
+.B salt.modules.iwtools.__virtual__()
+Only load the module if iwconfig is installed
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.iwtools.list_interfaces(style=None)
List all of the wireless interfaces
.sp
@@ -158556,6 +166884,16 @@ jenkins:
.UNINDENT
.INDENT 0.0
.TP
+.B salt.modules.jenkinsmod.__virtual__()
+Return virtual name of the module.
+.INDENT 7.0
+.TP
+.B Returns
+The virtual name of the module.
+.UNINDENT
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.jenkinsmod.build_job(name=None, parameters=None)
Initiate a build for the provided job.
.INDENT 7.0
@@ -158871,14 +167209,24 @@ salt \(aq*\(aq jenkins.plugin_installed pluginName
New in version 2017.7.0.
.sp
-Execute a groovy script on the jenkins master
+Execute a script on the jenkins master
.INDENT 7.0
.TP
.B Parameters
-\fBscript\fP \-\- The groovy script
+\fBscript\fP \-\- The script
.UNINDENT
.sp
CLI Example:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+salt \(aq*\(aq jenkins.run \(aqJenkins.instance.doSafeRestart()\(aq
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
@@ -158937,56 +167285,45 @@ use the latest salt code from github until the next release.
Refer to \fBjunos\fP for information on connecting to junos proxy.
.INDENT 0.0
.TP
-.B salt.modules.junos.cli(command=None, format=\(aqtext\(aq, **kwargs)
+.B salt.modules.junos.__virtual__()
+We need the Junos adapter libraries for this
+module to work. We also need a proxymodule entry in __opts__
+in the opts dictionary
+.UNINDENT
+.INDENT 0.0
+.TP
+.B salt.modules.junos.cli(command=None, **kwargs)
Executes the CLI commands and returns the output in specified format. (default is text) The output can also be stored in a file.
+.INDENT 7.0
+.TP
+.B command (required)
+The command to execute on the Junos CLI
+.TP
+.B format
+text
+Format in which to get the CLI output (either \fBtext\fP or \fBxml\fP)
+.TP
+.B dev_timeout
+30
+The NETCONF RPC timeout (in seconds)
+.TP
+.B dest
+Destination file where the RPC output is stored. Note that the file
+will be stored on the proxy minion. To push the files to the master use
+\fBcp.push\fP\&.
+.UNINDENT
.sp
-Usage:
+CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aqdevice_name\(aq junos.cli \(aqshow system commit\(aq
-
salt \(aqdevice_name\(aq junos.cli \(aqshow version\(aq dev_timeout=40
-
-salt \(aqdevice_name\(aq junos.cli \(aqshow system alarms\(aq \(aqxml\(aq dest=/home/user/cli_output.txt
+salt \(aqdevice_name\(aq junos.cli \(aqshow system alarms\(aq format=xml dest=/home/user/cli_output.txt
.ft P
.fi
-.UNINDENT
-.UNINDENT
-.INDENT 7.0
-.TP
-.B Parameters
-.INDENT 7.0
-.IP \(bu 2
-\fBRequired\fP \-\- .INDENT 2.0
-.IP \(bu 2
-command:
-The command that need to be executed on Junos CLI. (default = None)
-.UNINDENT
-
-.IP \(bu 2
-\fBOptional\fP \-\- .INDENT 2.0
-.IP \(bu 2
-format:
-Format in which to get the CLI output. (text or xml, default = \(aqtext\(aq)
-.IP \(bu 2
-.INDENT 2.0
-.TP
-.B kwargs: Keyworded arguments which can be provided like\-
-.INDENT 7.0
-.IP \(bu 2
-dev_timeout:
-Set NETCONF RPC timeout. Can be used for commands which
-take a while to execute. (default = 30 seconds)
-.IP \(bu 2
-dest:
-The destination file where the CLI output can be stored. (default = None)
-.UNINDENT
-.UNINDENT
-.UNINDENT
-
.UNINDENT
.UNINDENT
.UNINDENT
@@ -158994,65 +167331,60 @@ The destination file where the CLI output can be stored. (default
.TP
.B salt.modules.junos.commit(**kwargs)
To commit the changes loaded in the candidate configuration.
+.INDENT 7.0
+.TP
+.B dev_timeout
+30
+The NETCONF RPC timeout (in seconds)
+.TP
+.B comment
+Provide a comment for the commit
+.TP
+.B confirm
+Provide time in minutes for commit confirmation. If this option is
+specified, the commit will be rolled back in the specified amount of time
+unless the commit is confirmed.
+.TP
+.B sync
+False
+When \fBTrue\fP, on dual control plane systems, requests that the candidate
+configuration on one control plane be copied to the other control plane,
+checked for correct syntax, and committed on both Routing Engines.
+.TP
+.B force_sync
+False
+When \fBTrue\fP, on dual control plane systems, force the candidate
+configuration on one control plane to be copied to the other control
+plane.
+.TP
+.B full
+When \fBTrue\fP, requires all the daemons to check and evaluate the new
+configuration.
+.TP
+.B detail
+When \fBTrue\fP, return commit detail
+.UNINDENT
.sp
-Usage:
+CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aqdevice_name\(aq junos.commit comment=\(aqCommiting via saltstack\(aq detail=True
-
salt \(aqdevice_name\(aq junos.commit dev_timeout=60 confirm=10
-
salt \(aqdevice_name\(aq junos.commit sync=True dev_timeout=90
.ft P
.fi
.UNINDENT
-.UNINDENT
-.INDENT 7.0
-.TP
-.B Parameters
-\fBOptional\fP \-\- .INDENT 7.0
-.IP \(bu 2
-.INDENT 2.0
-.TP
-.B kwargs: Keyworded arguments which can be provided like\-
-.INDENT 7.0
-.IP \(bu 2
-dev_timeout:
-Set NETCONF RPC timeout. Can be used for commands which take a while to execute. (default = 30 seconds)
-.IP \(bu 2
-comment:
-Provide a comment to the commit. (default = None)
-.IP \(bu 2
-confirm:
-Provide time in minutes for commit confirmation. If this option is specified, the commit will be rollbacked in the given time unless the commit is confirmed.
-.IP \(bu 2
-sync:
-On dual control plane systems, requests that the candidate configuration on one control plane be copied to the other control plane,checked for correct syntax, and committed on both Routing Engines. (default = False)
-.IP \(bu 2
-force_sync:
-On dual control plane systems, force the candidate configuration
-on one control plane to be copied to the other control plane.
-.IP \(bu 2
-full:
-When set to True requires all the daemons to check and evaluate the new configuration.
-.IP \(bu 2
-detail:
-When true return commit detail.
-.UNINDENT
-.UNINDENT
-.UNINDENT
-
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.junos.commit_check()
-Perform a commit check on the configuration.
+Perform a commit check on the configuration
.sp
-Usage:
+CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
@@ -159066,10 +167398,16 @@ salt \(aqdevice_name\(aq junos.commit_check
.UNINDENT
.INDENT 0.0
.TP
-.B salt.modules.junos.diff(id=0)
-Gives the difference between the candidate and the current configuration.
+.B salt.modules.junos.diff(**kwargs)
+Returns the difference between the candidate and the current configuration
+.INDENT 7.0
+.TP
+.B id
+0
+The rollback ID value (0\-49)
+.UNINDENT
.sp
-Usage:
+CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
@@ -159079,16 +167417,6 @@ salt \(aqdevice_name\(aq junos.diff 3
.ft P
.fi
.UNINDENT
-.UNINDENT
-.INDENT 7.0
-.TP
-.B Parameters
-\fBOptional\fP \-\- .INDENT 7.0
-.IP \(bu 2
-id:
-The rollback id value [0\-49]. (default = 0)
-.UNINDENT
-
.UNINDENT
.UNINDENT
.INDENT 0.0
@@ -159097,7 +167425,7 @@ The rollback id value [0\-49]. (default = 0)
Displays the facts gathered during the connection.
These facts are also stored in Salt grains.
.sp
-Usage:
+CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
@@ -159116,7 +167444,7 @@ Reload the facts dictionary from the device. Usually only needed if,
the device configuration is changed by some other actor.
This function will also refresh the facts stored in the salt grains.
.sp
-Usage:
+CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
@@ -159131,9 +167459,17 @@ salt \(aqdevice_name\(aq junos.facts_refresh
.INDENT 0.0
.TP
.B salt.modules.junos.file_copy(src=None, dest=None)
-Copies the file from the local device to the junos device.
+Copies the file from the local device to the junos device
+.INDENT 7.0
+.TP
+.B src
+The source path where the file is kept.
+.TP
+.B dest
+The destination path on the where the file will be copied
+.UNINDENT
.sp
-Usage:
+CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
@@ -159143,19 +167479,6 @@ salt \(aqdevice_name\(aq junos.file_copy /home/m2/info.txt info_copy.txt
.ft P
.fi
.UNINDENT
-.UNINDENT
-.INDENT 7.0
-.TP
-.B Parameters
-\fBRequired\fP \-\- .INDENT 7.0
-.IP \(bu 2
-src:
-The sorce path where the file is kept.
-.IP \(bu 2
-dest:
-The destination path where the file will be copied.
-.UNINDENT
-
.UNINDENT
.UNINDENT
.INDENT 0.0
@@ -159163,99 +167486,91 @@ The destination path where the file will be copied.
.B salt.modules.junos.install_config(path=None, **kwargs)
Installs the given configuration file into the candidate configuration.
Commits the changes if the commit checks or throws an error.
+.INDENT 7.0
+.TP
+.B path (required)
+Path where the configuration/template file is present. If the file has
+a \fB\&.conf\fP extension, the content is treated as text format. If the
+file has a \fB\&.xml\fP extension, the content is treated as XML format. If
+the file has a \fB\&.set\fP extension, the content is treated as Junos OS
+\fBset\fP commands.
+.TP
+.B mode
+exclusive
+The mode in which the configuration is locked. Can be one of
+\fBprivate\fP, \fBdynamic\fP, \fBbatch\fP, \fBexclusive\fP\&.
+.TP
+.B dev_timeout
+30
+Set NETCONF RPC timeout. Can be used for commands which take a while to
+execute.
+.TP
+.B overwrite
+False
+Set to \fBTrue\fP if you want this file is to completely replace the
+configuration file.
+.TP
+.B replace
+False
+Specify whether the configuration file uses \fBreplace:\fP statements. If
+\fBTrue\fP, only those statements under the \fBreplace\fP tag will be
+changed.
+.TP
+.B format
+Determines the format of the contents
+.TP
+.B update
+False
+Compare a complete loaded configuration against the candidate
+configuration. For each hierarchy level or configuration object that is
+different in the two configurations, the version in the loaded
+configuration replaces the version in the candidate configuration. When
+the configuration is later committed, only system processes that are
+affected by the changed configuration elements parse the new
+configuration. This action is supported from PyEZ 2.1.
+.TP
+.B comment
+Provide a comment for the commit
+.TP
+.B confirm
+Provide time in minutes for commit confirmation. If this option is
+specified, the commit will be rolled back in the specified amount of time
+unless the commit is confirmed.
+.TP
+.B diffs_file
+Path to the file where the diff (difference in old configuration and the
+committed configuration) will be stored. Note that the file will be
+stored on the proxy minion. To push the files to the master use
+\fBcp.push\fP\&.
+.TP
+.B template_vars
+Variables to be passed into the template processing engine in addition to
+those present in pillar, the minion configuration, grains, etc. You may
+reference these variables in your template like so:
+.INDENT 7.0
+.INDENT 3.5
.sp
-Usage:
+.nf
+.ft C
+{{ template_vars["var_name"] }}
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.UNINDENT
+.sp
+CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aqdevice_name\(aq junos.install_config \(aqsalt://production/network/routers/config.set\(aq
-
salt \(aqdevice_name\(aq junos.install_config \(aqsalt://templates/replace_config.conf\(aq replace=True comment=\(aqCommitted via SaltStack\(aq
-
salt \(aqdevice_name\(aq junos.install_config \(aqsalt://my_new_configuration.conf\(aq dev_timeout=300 diffs_file=\(aq/salt/confs/old_config.conf\(aq overwrite=True
-
salt \(aqdevice_name\(aq junos.install_config \(aqsalt://syslog_template.conf\(aq template_vars=\(aq{"syslog_host": "10.180.222.7"}\(aq
.ft P
.fi
-.UNINDENT
-.UNINDENT
-.INDENT 7.0
-.TP
-.B Parameters
-.INDENT 7.0
-.IP \(bu 2
-\fBRequired\fP \-\- .INDENT 2.0
-.IP \(bu 2
-path:
-Path where the configuration/template file is present. If the file has a \(aq\fI\&.conf\(aq extension,
-the content is treated as text format. If the file has a \(aq\fP\&.xml\(aq extension,
-the content is treated as XML format. If the file has a \(aq
-.nf
-*
-.fi
-\&.set\(aq extension,
-the content is treated as Junos OS \(aqset\(aq commands.(default = None)
-.UNINDENT
-
-.IP \(bu 2
-\fBOptional\fP \-\- .INDENT 2.0
-.IP \(bu 2
-.INDENT 2.0
-.TP
-.B kwargs: Keyworded arguments which can be provided like\-
-.INDENT 7.0
-.IP \(bu 2
-mode: The mode in which the configuration is locked.
-(Options: private, dynamic, batch, exclusive; default= exclusive)
-.IP \(bu 2
-dev_timeout:
-Set NETCONF RPC timeout. Can be used for commands which
-take a while to execute. (default = 30 seconds)
-.IP \(bu 2
-overwrite:
-Set to True if you want this file is to completely replace the configuration file. (default = False)
-.IP \(bu 2
-replace:
-Specify whether the configuration file uses "replace:" statements.
-Those statements under the \(aqreplace\(aq tag will only be changed. (default = False)
-.IP \(bu 2
-format:
-Determines the format of the contents.
-.IP \(bu 2
-update:
-Compare a complete loaded configuration against
-the candidate configuration. For each hierarchy level or
-configuration object that is different in the two configurations,
-the version in the loaded configuration replaces the version in the
-candidate configuration. When the configuration is later committed,
-only system processes that are affected by the changed configuration
-elements parse the new configuration. This action is supported from
-PyEZ 2.1 (default = False)
-.IP \(bu 2
-comment:
-Provide a comment to the commit. (default = None)
-.IP \(bu 2
-confirm:
-Provide time in minutes for commit confirmation.
-If this option is specified, the commit will be rollbacked in the given time unless the commit is confirmed.
-.IP \(bu 2
-diffs_file:
-Path to the file where the diff (difference in old configuration
-and the committed configuration) will be stored.(default = None)
-Note that the file will be stored on the proxy minion. To push the
-files to the master use the salt\(aqs following execution module: \fBcp.push\fP
-.IP \(bu 2
-template_vars:
-Variables to be passed into the template processing engine in addition
-to those present in __pillar__, __opts__, __grains__, etc.
-You may reference these variables in your template like so:
-{{ template_vars["var_name"] }}
-.UNINDENT
-.UNINDENT
-.UNINDENT
-
.UNINDENT
.UNINDENT
.UNINDENT
@@ -159264,52 +167579,34 @@ You may reference these variables in your template like so:
.B salt.modules.junos.install_os(path=None, **kwargs)
Installs the given image on the device. After the installation is complete the device is rebooted,
if reboot=True is given as a keyworded argument.
+.INDENT 7.0
+.TP
+.B path (required)
+Path where the image file is present on the proxy minion
+.TP
+.B dev_timeout
+30
+The NETCONF RPC timeout (in seconds)
+.TP
+.B reboot
+False
+Whether to reboot after installation
+.TP
+.B no_copy
+False
+If \fBTrue\fP the software package will not be SCP’d to the device
+.UNINDENT
.sp
-Usage:
+CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aqdevice_name\(aq junos.install_os \(aqsalt://images/junos_image.tgz\(aq reboot=True
-
salt \(aqdevice_name\(aq junos.install_os \(aqsalt://junos_16_1.tgz\(aq dev_timeout=300
.ft P
.fi
-.UNINDENT
-.UNINDENT
-.INDENT 7.0
-.TP
-.B Parameters
-.INDENT 7.0
-.IP \(bu 2
-\fBRequired\fP \-\- .INDENT 2.0
-.IP \(bu 2
-path:
-Path where the image file is present on the proxy minion.
-.UNINDENT
-
-.IP \(bu 2
-\fBOptional\fP \-\- .INDENT 2.0
-.IP \(bu 2
-.INDENT 2.0
-.TP
-.B kwargs: keyworded arguments to be given such as dev_timeout, reboot etc
-.INDENT 7.0
-.IP \(bu 2
-dev_timeout:
-Set NETCONF RPC timeout. Can be used to RPCs which
-take a while to execute. (default = 30 seconds)
-.IP \(bu 2
-reboot:
-Whether to reboot after installation (default = False)
-.IP \(bu 2
-no_copy:
-When True the software package will not be SCP’d to the device. (default = False)
-.UNINDENT
-.UNINDENT
-.UNINDENT
-
.UNINDENT
.UNINDENT
.UNINDENT
@@ -159317,8 +167614,56 @@ When True the software package will not be SCP’d to the device.
.TP
.B salt.modules.junos.load(path=None, **kwargs)
Loads the configuration from the file provided onto the device.
+.INDENT 7.0
+.TP
+.B path (required)
+Path where the configuration/template file is present. If the file has
+a \fB\&.conf\fP extension, the content is treated as text format. If the
+file has a \fB\&.xml\fP extension, the content is treated as XML format. If
+the file has a \fB\&.set\fP extension, the content is treated as Junos OS
+\fBset\fP commands.
+.TP
+.B overwrite
+False
+Set to \fBTrue\fP if you want this file is to completely replace the
+configuration file.
+.TP
+.B replace
+False
+Specify whether the configuration file uses \fBreplace:\fP statements. If
+\fBTrue\fP, only those statements under the \fBreplace\fP tag will be
+changed.
+.TP
+.B format
+Determines the format of the contents
+.TP
+.B update
+False
+Compare a complete loaded configuration against the candidate
+configuration. For each hierarchy level or configuration object that is
+different in the two configurations, the version in the loaded
+configuration replaces the version in the candidate configuration. When
+the configuration is later committed, only system processes that are
+affected by the changed configuration elements parse the new
+configuration. This action is supported from PyEZ 2.1.
+.TP
+.B template_vars
+Variables to be passed into the template processing engine in addition to
+those present in pillar, the minion configuration, grains, etc. You may
+reference these variables in your template like so:
+.INDENT 7.0
+.INDENT 3.5
.sp
-Usage:
+.nf
+.ft C
+{{ template_vars["var_name"] }}
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.UNINDENT
+.sp
+CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
@@ -159333,63 +167678,6 @@ salt \(aqdevice_name\(aq junos.load \(aqsalt://my_new_configuration.conf\(aq ove
salt \(aqdevice_name\(aq junos.load \(aqsalt://syslog_template.conf\(aq template_vars=\(aq{"syslog_host": "10.180.222.7"}\(aq
.ft P
.fi
-.UNINDENT
-.UNINDENT
-.INDENT 7.0
-.TP
-.B Parameters
-.INDENT 7.0
-.IP \(bu 2
-\fBRequired\fP \-\- .INDENT 2.0
-.IP \(bu 2
-path:
-Path where the configuration/template file is present. If the file has a \(aq\fI\&.conf\(aq extension,
-the content is treated as text format. If the file has a \(aq\fP\&.xml\(aq extension,
-the content is treated as XML format. If the file has a \(aq
-.nf
-*
-.fi
-\&.set\(aq extension,
-the content is treated as Junos OS \(aqset\(aq commands.(default = None)
-.UNINDENT
-
-.IP \(bu 2
-\fBOptional\fP \-\- .INDENT 2.0
-.IP \(bu 2
-.INDENT 2.0
-.TP
-.B kwargs: Keyworded arguments which can be provided like\-
-.INDENT 7.0
-.IP \(bu 2
-overwrite:
-Set to True if you want this file is to completely replace the configuration file. (default = False)
-.IP \(bu 2
-replace:
-Specify whether the configuration file uses "replace:" statements.
-Those statements under the \(aqreplace\(aq tag will only be changed. (default = False)
-.IP \(bu 2
-format:
-Determines the format of the contents.
-.IP \(bu 2
-update:
-Compare a complete loaded configuration against
-the candidate configuration. For each hierarchy level or
-configuration object that is different in the two configurations,
-the version in the loaded configuration replaces the version in the
-candidate configuration. When the configuration is later committed,
-only system processes that are affected by the changed configuration
-elements parse the new configuration. This action is supported from
-PyEZ 2.1 (default = False)
-.IP \(bu 2
-template_vars:
-Variables to be passed into the template processing engine in addition
-to those present in __pillar__, __opts__, __grains__, etc.
-You may reference these variables in your template like so:
-{{ template_vars["var_name"] }}
-.UNINDENT
-.UNINDENT
-.UNINDENT
-
.UNINDENT
.UNINDENT
.UNINDENT
@@ -159402,13 +167690,14 @@ is a non\-blocking call.
\fBNOTE:\fP
.INDENT 7.0
.INDENT 3.5
-Any user who wishes to use lock, must necessarily unlock the
-configuration too. Ensure \fI\%unlock\fP
-is called in the same orchestration run in which the lock is called.
+When locking, it is important to remember to call
+\fI\%junos.unlock\fP once finished. If
+locking during orchestration, remember to include a step in the
+orchestration job to unlock.
.UNINDENT
.UNINDENT
.sp
-Usage:
+CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
@@ -159423,71 +167712,78 @@ salt \(aqdevice_name\(aq junos.lock
.INDENT 0.0
.TP
.B salt.modules.junos.ping(dest_ip=None, **kwargs)
-To send ping RPC to a device.
+Send a ping RPC to a device
+.INDENT 7.0
+.TP
+.B dest_ip
+The IP of the device to ping
+.TP
+.B dev_timeout
+30
+The NETCONF RPC timeout (in seconds)
+.TP
+.B rapid
+False
+When \fBTrue\fP, executes ping at 100pps instead of 1pps
+.TP
+.B ttl
+Maximum number of IP routers (IP hops) allowed between source and
+destination
+.TP
+.B routing_instance
+Name of the routing instance to use to send the ping
+.TP
+.B interface
+Interface used to send traffic
+.TP
+.B count
+5
+Number of packets to send
+.UNINDENT
.sp
-Usage:
+CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aqdevice_name\(aq junos.ping \(aq8.8.8.8\(aq count=5
-
salt \(aqdevice_name\(aq junos.ping \(aq8.8.8.8\(aq ttl=1 rapid=True
.ft P
.fi
-.UNINDENT
-.UNINDENT
-.INDENT 7.0
-.TP
-.B Parameters
-.INDENT 7.0
-.IP \(bu 2
-\fBRequired\fP \-\- .INDENT 2.0
-.IP \(bu 2
-dest_ip:
-The IP which is to be pinged. (default = None)
-.UNINDENT
-
-.IP \(bu 2
-\fBOptional\fP \-\- .INDENT 2.0
-.IP \(bu 2
-.INDENT 2.0
-.TP
-.B kwargs: Keyworded arguments which can be provided like\-
-.INDENT 7.0
-.IP \(bu 2
-dev_timeout:
-Set NETCONF RPC timeout. Can be used for commands which
-take a while to execute. (default = 30 seconds)
-.IP \(bu 2
-rapid:
-Setting this to True executes ping at 100pps instead of 1pps. (default = False)
-.IP \(bu 2
-ttl:
-Maximum number of IP routers (IP hops) allowed between source and destination.
-.IP \(bu 2
-routing_instance:
-Name of the routing instance to use to send the ping.
-.IP \(bu 2
-interface:
-Interface used to send traffic out.
-.IP \(bu 2
-count:
-Number of packets to send. (default = 5)
-.UNINDENT
-.UNINDENT
-.UNINDENT
-
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
-.B salt.modules.junos.rollback(id=0, **kwargs)
-To rollback the last committed configuration changes and commit the same.
+.B salt.modules.junos.rollback(**kwargs)
+Roll back the last committed configuration changes and commit
+.INDENT 7.0
+.TP
+.B id
+0
+The rollback ID value (0\-49)
+.TP
+.B dev_timeout
+30
+The NETCONF RPC timeout (in seconds)
+.TP
+.B comment
+Provide a comment for the commit
+.TP
+.B confirm
+Provide time in minutes for commit confirmation. If this option is
+specified, the commit will be rolled back in the specified amount of time
+unless the commit is confirmed.
+.TP
+.B diffs_file
+Path to the file where the diff (difference in old configuration and the
+committed configuration) will be stored. Note that the file will be
+stored on the proxy minion. To push the files to the master use
+\fBcp.push\fP\&.
+.UNINDENT
.sp
-Usage:
+CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
@@ -159497,113 +167793,79 @@ salt \(aqdevice_name\(aq junos.rollback 10
.ft P
.fi
.UNINDENT
-.UNINDENT
-.INDENT 7.0
-.TP
-.B Parameters
-\fBOptional\fP \-\- .INDENT 7.0
-.IP \(bu 2
-id:
-The rollback id value [0\-49]. (default = 0)
-.IP \(bu 2
-.INDENT 2.0
-.TP
-.B kwargs: Keyworded arguments which can be provided like\-
-.INDENT 7.0
-.IP \(bu 2
-dev_timeout:
-Set NETCONF RPC timeout. Can be used for commands which
-take a while to execute. (default = 30 seconds)
-.IP \(bu 2
-comment:
-Provide a comment to the commit. (default = None)
-.IP \(bu 2
-confirm:
-Provide time in minutes for commit confirmation. If this option is specified, the commit will be rollbacked in the given time unless the commit is confirmed.
-.IP \(bu 2
-diffs_file:
-Path to the file where any diffs will be written. (default = None)
-.UNINDENT
-.UNINDENT
-.UNINDENT
-
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
-.B salt.modules.junos.rpc(cmd=None, dest=None, format=\(aqxml\(aq, **kwargs)
-This function executes the rpc provided as arguments on the junos device.
+.B salt.modules.junos.rpc(cmd=None, dest=None, **kwargs)
+This function executes the RPC provided as arguments on the junos device.
The returned data can be stored in a file.
+.INDENT 7.0
+.TP
+.B cmd
+The RPC to be executed
+.TP
+.B dest
+Destination file where the RPC output is stored. Note that the file
+will be stored on the proxy minion. To push the files to the master use
+\fBcp.push\fP\&.
+.TP
+.B format
+xml
+The format in which the RPC reply is received from the device
+.TP
+.B dev_timeout
+30
+The NETCONF RPC timeout (in seconds)
+.TP
+.B filter
+Used with the \fBget\-config\fP RPC to get specific configuration
+.TP
+.B terse
+False
+Amount of information you want
+.TP
+.B interface_name
+Name of the interface to query
+.UNINDENT
.sp
-Usage:
+CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
-salt \(aqdevice\(aq junos.rpc \(aqget_config\(aq \(aq/var/log/config.txt\(aq \(aqtext\(aq filter=\(aq\(aq
-
-salt \(aqdevice\(aq junos.rpc \(aqget\-interface\-information\(aq \(aq/home/user/interface.xml\(aq interface_name=\(aqlo0\(aq terse=True
-
-salt \(aqdevice\(aq junos.rpc \(aqget\-chassis\-inventory\(aq
+salt \(aqdevice\(aq junos.rpc get_config /var/log/config.txt format=text filter=\(aq\(aq
+salt \(aqdevice\(aq junos.rpc get\-interface\-information /home/user/interface.xml interface_name=\(aqlo0\(aq terse=True
+salt \(aqdevice\(aq junos.rpc get\-chassis\-inventory
.ft P
.fi
-.UNINDENT
-.UNINDENT
-.INDENT 7.0
-.TP
-.B Parameters
-.INDENT 7.0
-.IP \(bu 2
-\fBRequired\fP \-\- .INDENT 2.0
-.IP \(bu 2
-cmd:
-The rpc to be executed. (default = None)
-.UNINDENT
-
-.IP \(bu 2
-\fBOptional\fP \-\- .INDENT 2.0
-.IP \(bu 2
-dest:
-Destination file where the rpc output is stored. (default = None)
-Note that the file will be stored on the proxy minion. To push the
-files to the master use the salt\(aqs following execution module:
-\fBcp.push\fP
-.IP \(bu 2
-format:
-The format in which the rpc reply is received from the device.
-(default = xml)
-.IP \(bu 2
-.INDENT 2.0
-.TP
-.B kwargs: keyworded arguments taken by rpc call like\-
-.INDENT 7.0
-.IP \(bu 2
-dev_timeout:
-Set NETCONF RPC timeout. Can be used for commands which
-take a while to execute. (default= 30 seconds)
-.IP \(bu 2
-filter:
-Only to be used with \(aqget\-config\(aq rpc to get specific configuration.
-.IP \(bu 2
-terse:
-Amount of information you want.
-.IP \(bu 2
-interface_name:
-Name of the interface whose information you want.
-.UNINDENT
-.UNINDENT
-.UNINDENT
-
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.junos.set_hostname(hostname=None, **kwargs)
-To set the name of the device.
+Set the device\(aqs hostname
+.INDENT 7.0
+.TP
+.B hostname
+The name to be set
+.TP
+.B dev_timeout
+30
+The NETCONF RPC timeout (in seconds)
+.TP
+.B comment
+Provide a comment to the commit
+.TP
+.B confirm
+Provide time in minutes for commit confirmation. If this option is
+specified, the commit will be rolled back in the specified amount of time
+unless the commit is confirmed.
+.UNINDENT
.sp
-Usage:
+CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
@@ -159612,94 +167874,59 @@ Usage:
salt \(aqdevice_name\(aq junos.set_hostname salt\-device
.ft P
.fi
-.UNINDENT
-.UNINDENT
-.INDENT 7.0
-.TP
-.B Parameters
-.INDENT 7.0
-.IP \(bu 2
-\fBRequired\fP \-\- .INDENT 2.0
-.IP \(bu 2
-hostname: The name to be set. (default = None)
-.UNINDENT
-
-.IP \(bu 2
-\fBOptional\fP \-\- .INDENT 2.0
-.IP \(bu 2
-.INDENT 2.0
-.TP
-.B kwargs: Keyworded arguments which can be provided like\-
-.INDENT 7.0
-.IP \(bu 2
-dev_timeout:
-Set NETCONF RPC timeout. Can be used for commands
-which take a while to execute. (default = 30 seconds)
-.IP \(bu 2
-comment:
-Provide a comment to the commit. (default = None)
-.IP \(bu 2
-confirm:
-Provide time in minutes for commit confirmation. If this option is specified, the commit will be rollbacked in the given time unless the commit is confirmed.
-.UNINDENT
-.UNINDENT
-.UNINDENT
-
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.junos.shutdown(**kwargs)
-Shut down (power off) or reboot a device running Junos OS.
-This includes all Routing Engines in a Virtual Chassis or a dual Routing Engine system.
+Shut down (power off) or reboot a device running Junos OS. This includes
+all Routing Engines in a Virtual Chassis or a dual Routing Engine system.
+.INDENT 7.0
+.INDENT 3.5
.sp
-Usage:
+\fBNOTE:\fP
+.INDENT 0.0
+.INDENT 3.5
+One of \fBshutdown\fP or \fBreboot\fP must be set to \fBTrue\fP or no
+action will be taken.
+.UNINDENT
+.UNINDENT
+.UNINDENT
+.UNINDENT
+.INDENT 7.0
+.TP
+.B shutdown
+False
+Set this to \fBTrue\fP if you want to shutdown the machine. This is a
+safety mechanism so that the user does not accidentally shutdown the
+junos device.
+.TP
+.B reboot
+False
+If \fBTrue\fP, reboot instead of shutting down
+.TP
+.B at
+Used when rebooting, to specify the date and time the reboot should take
+place. The value of this option must match the JunOS CLI reboot syntax.
+.TP
+.B in_min
+Used when shutting down. Specify the delay (in minutes) before the
+device will be shut down.
+.UNINDENT
+.sp
+CLI Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
salt \(aqdevice_name\(aq junos.shutdown reboot=True
-
salt \(aqdevice_name\(aq junos.shutdown shutdown=True in_min=10
-
salt \(aqdevice_name\(aq junos.shutdown shutdown=True
.ft P
.fi
.UNINDENT
-.UNINDENT
-.INDENT 7.0
-.TP
-.B Parameters
-\fBOptional\fP \-\- .INDENT 7.0
-.IP \(bu 2
-.INDENT 2.0
-.TP
-.B kwargs:
-.INDENT 7.0
-.IP \(bu 2
-shutdown:
-Set this to true if you want to shutdown the machine.
-(default=False, this is a safety mechanism so that the user does
-not accidentally shutdown the junos device.)
-.IP \(bu 2
-reboot:
-Whether to reboot instead of shutdown. (default=False)
-Note that either one of the above arguments has to be specified
-(shutdown or reboot) for this function to work.
-.IP \(bu 2
-at:
-Date and time the reboot should take place. The
-string must match the junos cli reboot syntax
-(To be used only if reboot=True)
-.IP \(bu 2
-in_min:
-Specify delay in minutes for shutdown
-.UNINDENT
-.UNINDENT
-.UNINDENT
-
.UNINDENT
.UNINDENT
.INDENT 0.0
@@ -159707,7 +167934,7 @@ Specify delay in minutes for shutdown
.B salt.modules.junos.unlock()
Unlocks the candidate configuration.
.sp
-Usage:
+CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
@@ -159724,7 +167951,7 @@ salt \(aqdevice_name\(aq junos.unlock
.B salt.modules.junos.zeroize()
Resets the device to default factory settings
.sp
-Usage:
+CLI Example:
.INDENT 7.0
.INDENT 3.5
.sp
@@ -159758,6 +167985,11 @@ Add (auto)scalling
.UNINDENT
.INDENT 0.0
.TP
+.B salt.modules.k8s.__virtual__()
+Load load if python\-requests is installed.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.k8s.create_namespace(name, apiserver_url=None)
New in version 2016.3.0.
@@ -160459,6 +168691,11 @@ Module for managing keyboards on supported POSIX\-like systems using
systemd, or such as Redhat, Debian and Gentoo.
.INDENT 0.0
.TP
+.B salt.modules.keyboard.__virtual__()
+Only works with systemd or on supported POSIX\-like systems
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.keyboard.get_sys()
Get current system keyboard setting
.sp
@@ -160608,6 +168845,12 @@ salt \(aq*\(aq keystone.tenant_list profile=openstack1
.UNINDENT
.INDENT 0.0
.TP
+.B salt.modules.keystone.__virtual__()
+Only load this module if keystone
+is installed on this minion.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.keystone.api_version(profile=None, **connection_args)
Returns the API version derived from endpoint\(aqs response.
.sp
@@ -161409,6 +169652,11 @@ salt \(aq*\(aq keystone.user_verify_password user_id=c965f79c4f864eaaa9c3b41904e
Module to manage Linux kernel modules
.INDENT 0.0
.TP
+.B salt.modules.kmod.__virtual__()
+Only runs on Linux systems
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.kmod.available()
Return a list of all available kernel modules
.sp
@@ -161594,6 +169842,16 @@ It\(aqs base64 encoded certificates/keys in one line.
.sp
For an item only one field should be provided. Either a \fIdata\fP or a \fIfile\fP entry.
In case both are provided the \fIfile\fP entry is preferred.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+salt \(aq*\(aq kubernetes.nodes api_url=http://k8s\-api\-server:port api_user=myuser api_password=pass
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
.sp
\fBWARNING:\fP
.INDENT 0.0
@@ -161609,6 +169867,11 @@ kubernetes.context
.UNINDENT
.INDENT 0.0
.TP
+.B salt.modules.kubernetes.__virtual__()
+Check dependencies
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.kubernetes.configmaps(namespace=\(aqdefault\(aq, **kwargs)
Return a list of kubernetes configmaps defined in the namespace
.sp
@@ -162115,6 +170378,11 @@ plistlib Python module
.UNINDENT
.INDENT 0.0
.TP
+.B salt.modules.launchctl.__virtual__()
+Only work on MacOS
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.launchctl.available(job_label)
Check that the given service is available.
.sp
@@ -162277,6 +170545,11 @@ salt \(aq*\(aq service.stop /System/Library/LaunchDaemons/org.ntp.ntpd.plist
Support for Layman
.INDENT 0.0
.TP
+.B salt.modules.layman.__virtual__()
+Only work on Gentoo systems with layman installed
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.layman.add(overlay)
Add the given overlay from the cached remote list to your locally
installed overlays. Specify \(aqALL\(aq to add all overlays from the
@@ -162409,6 +170682,11 @@ have a different type.
.UNINDENT
.INDENT 0.0
.TP
+.B salt.modules.ldap3.__virtual__()
+Only load this module if the Python ldap module is present
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.ldap3.add(connect_spec, dn, attributes)
Add an entry to an LDAP database.
.INDENT 7.0
@@ -163000,6 +171278,11 @@ badness may ensue \- you have been warned.
.UNINDENT
.INDENT 0.0
.TP
+.B salt.modules.ldapmod.__virtual__()
+Only load this module if the ldap config is set
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.ldapmod.search(filter, dn=None, scope=None, attrs=None, **kwargs)
Run an arbitrary LDAP query and return the results.
.sp
@@ -163046,6 +171329,366 @@ scope=1 attrs=\(aq\(aq server=\(aqlocalhost\(aq port=\(aq7393\(aq tls=True bindp
.UNINDENT
.UNINDENT
.UNINDENT
+.SS salt.modules.libcloud_dns module
+.sp
+Connection module for Apache Libcloud DNS management
+.sp
+New in version 2016.11.0.
+
+.INDENT 0.0
+.TP
+.B configuration
+This module uses a configuration profile for one or multiple DNS providers
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+libcloud_dns:
+ profile_test1:
+ driver: cloudflare
+ key: 12345
+ secret: mysecret
+ profile_test2:
+ driver: godaddy
+ key: 12345
+ secret: mysecret
+ shopper_id: 12345
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.TP
+.B depends
+apache\-libcloud
+.UNINDENT
+.INDENT 0.0
+.TP
+.B salt.modules.libcloud_dns.__virtual__()
+Only load if libcloud libraries exist.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B salt.modules.libcloud_dns.create_record(name, zone_id, type, data, profile)
+Create a new record.
+.INDENT 7.0
+.TP
+.B Parameters
+.INDENT 7.0
+.IP \(bu 2
+\fBname\fP (\fBstr\fP) \-\- Record name without the domain name (e.g. www).
+Note: If you want to create a record for a base domain
+name, you should specify empty string (\(aq\(aq) for this
+argument.
+.IP \(bu 2
+\fBzone_id\fP (\fBstr\fP) \-\- Zone where the requested record is created.
+.IP \(bu 2
+\fBtype\fP (\fBstr\fP) \-\- DNS record type (A, AAAA, ...).
+.IP \(bu 2
+\fBdata\fP (\fBstr\fP) \-\- Data for the record (depends on the record type).
+.IP \(bu 2
+\fBprofile\fP (\fBstr\fP) \-\- The profile key
+.UNINDENT
+.UNINDENT
+.sp
+CLI Example:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+salt myminion libcloud_dns.create_record www google.com A 12.32.12.2 profile1
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.UNINDENT
+.INDENT 0.0
+.TP
+.B salt.modules.libcloud_dns.create_zone(domain, profile, type=\(aqmaster\(aq, ttl=None)
+Create a new zone.
+.INDENT 7.0
+.TP
+.B Parameters
+.INDENT 7.0
+.IP \(bu 2
+\fBdomain\fP (\fBstr\fP) \-\- Zone domain name (e.g. example.com)
+.IP \(bu 2
+\fBprofile\fP (\fBstr\fP) \-\- The profile key
+.IP \(bu 2
+\fBtype\fP (\fBstr\fP) \-\- Zone type (master / slave).
+.IP \(bu 2
+\fBttl\fP (\fBint\fP) \-\- TTL for new records. (optional)
+.UNINDENT
+.UNINDENT
+.sp
+CLI Example:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+salt myminion libcloud_dns.create_zone google.com profile1
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.UNINDENT
+.INDENT 0.0
+.TP
+.B salt.modules.libcloud_dns.delete_record(zone_id, record_id, profile)
+Delete a record.
+.INDENT 7.0
+.TP
+.B Parameters
+.INDENT 7.0
+.IP \(bu 2
+\fBzone_id\fP (\fBstr\fP) \-\- Zone to delete.
+.IP \(bu 2
+\fBrecord_id\fP (\fBstr\fP) \-\- Record to delete.
+.IP \(bu 2
+\fBprofile\fP (\fBstr\fP) \-\- The profile key
+.UNINDENT
+.TP
+.B Return type
+\fBbool\fP
+.UNINDENT
+.sp
+CLI Example:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+salt myminion libcloud_dns.delete_record google.com www profile1
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.UNINDENT
+.INDENT 0.0
+.TP
+.B salt.modules.libcloud_dns.delete_zone(zone_id, profile)
+Delete a zone.
+.INDENT 7.0
+.TP
+.B Parameters
+.INDENT 7.0
+.IP \(bu 2
+\fBzone_id\fP (\fBstr\fP) \-\- Zone to delete.
+.IP \(bu 2
+\fBprofile\fP (\fBstr\fP) \-\- The profile key
+.UNINDENT
+.TP
+.B Return type
+\fBbool\fP
+.UNINDENT
+.sp
+CLI Example:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+salt myminion libcloud_dns.delete_zone google.com profile1
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.UNINDENT
+.INDENT 0.0
+.TP
+.B salt.modules.libcloud_dns.get_bind_data(zone_id, profile)
+Export Zone to the BIND compatible format.
+.INDENT 7.0
+.TP
+.B Parameters
+.INDENT 7.0
+.IP \(bu 2
+\fBzone_id\fP (\fBstr\fP) \-\- Zone to export.
+.IP \(bu 2
+\fBprofile\fP (\fBstr\fP) \-\- The profile key
+.UNINDENT
+.TP
+.B Returns
+Zone data in BIND compatible format.
+.TP
+.B Return type
+\fBstr\fP
+.UNINDENT
+.sp
+CLI Example:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+salt myminion libcloud_dns.get_bind_data google.com profile1
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.UNINDENT
+.INDENT 0.0
+.TP
+.B salt.modules.libcloud_dns.get_record(zone_id, record_id, profile)
+Get record information for the given zone_id on the given profile
+.INDENT 7.0
+.TP
+.B Parameters
+.INDENT 7.0
+.IP \(bu 2
+\fBzone_id\fP (\fBstr\fP) \-\- Zone to export.
+.IP \(bu 2
+\fBrecord_id\fP (\fBstr\fP) \-\- Record to delete.
+.IP \(bu 2
+\fBprofile\fP (\fBstr\fP) \-\- The profile key
+.UNINDENT
+.UNINDENT
+.sp
+CLI Example:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+salt myminion libcloud_dns.get_record google.com www profile1
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.UNINDENT
+.INDENT 0.0
+.TP
+.B salt.modules.libcloud_dns.get_zone(zone_id, profile)
+Get zone information for the given zone_id on the given profile
+.INDENT 7.0
+.TP
+.B Parameters
+.INDENT 7.0
+.IP \(bu 2
+\fBzone_id\fP (\fBstr\fP) \-\- Zone to export.
+.IP \(bu 2
+\fBprofile\fP (\fBstr\fP) \-\- The profile key
+.UNINDENT
+.UNINDENT
+.sp
+CLI Example:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+salt myminion libcloud_dns.get_zone google.com profile1
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.UNINDENT
+.INDENT 0.0
+.TP
+.B salt.modules.libcloud_dns.list_record_types(profile)
+List available record types for the given profile, e.g. A, AAAA
+.INDENT 7.0
+.TP
+.B Parameters
+\fBprofile\fP (\fBstr\fP) \-\- The profile key
+.UNINDENT
+.sp
+CLI Example:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+salt myminion libcloud_dns.list_record_types profile1
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.UNINDENT
+.INDENT 0.0
+.TP
+.B salt.modules.libcloud_dns.list_records(zone_id, profile)
+List records for the given zone_id on the given profile
+.INDENT 7.0
+.TP
+.B Parameters
+.INDENT 7.0
+.IP \(bu 2
+\fBzone_id\fP (\fBstr\fP) \-\- Zone to export.
+.IP \(bu 2
+\fBprofile\fP (\fBstr\fP) \-\- The profile key
+.UNINDENT
+.UNINDENT
+.sp
+CLI Example:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+salt myminion libcloud_dns.list_records google.com profile1
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.UNINDENT
+.INDENT 0.0
+.TP
+.B salt.modules.libcloud_dns.list_zones(profile)
+List zones for the given profile
+.INDENT 7.0
+.TP
+.B Parameters
+\fBprofile\fP (\fBstr\fP) \-\- The profile key
+.UNINDENT
+.sp
+CLI Example:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+salt myminion libcloud_dns.list_zones profile1
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.UNINDENT
+.INDENT 0.0
+.TP
+.B salt.modules.libcloud_dns.update_zone(zone_id, domain, profile, type=\(aqmaster\(aq, ttl=None)
+Update an existing zone.
+.INDENT 7.0
+.TP
+.B Parameters
+.INDENT 7.0
+.IP \(bu 2
+\fBzone_id\fP (\fBstr\fP) \-\- Zone ID to update.
+.IP \(bu 2
+\fBdomain\fP (\fBstr\fP) \-\- Zone domain name (e.g. example.com)
+.IP \(bu 2
+\fBprofile\fP (\fBstr\fP) \-\- The profile key
+.IP \(bu 2
+\fBtype\fP (\fBstr\fP) \-\- Zone type (master / slave).
+.IP \(bu 2
+\fBttl\fP (\fBint\fP) \-\- TTL for new records. (optional)
+.UNINDENT
+.UNINDENT
+.sp
+CLI Example:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+salt myminion libcloud_dns.update_zone google.com google.com profile1 type=slave
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.UNINDENT
.SS salt.modules.linux_acl
.sp
Support for Linux File Access Control Lists
@@ -163053,6 +171696,11 @@ Support for Linux File Access Control Lists
The Linux ACL module requires the \fIgetfacl\fP and \fIsetfacl\fP binaries.
.INDENT 0.0
.TP
+.B salt.modules.linux_acl.__virtual__()
+Only load the module if getfacl is installed
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.linux_acl.delfacl(acl_type, acl_name=\(aq\(aq, *args, **kwargs)
Remove specific FACL from the specified file(s)
.sp
@@ -163153,6 +171801,11 @@ salt \(aq*\(aq acl.wipefacls /tmp/house/kitchen /tmp/house/livingroom recursive=
The networking module for Non\-RH/Deb Linux distros
.INDENT 0.0
.TP
+.B salt.modules.linux_ip.__virtual__()
+Confine this module to Non\-RH/Deb Linux distros
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.linux_ip.down(iface, iface_type=None)
Shutdown a network interface
.sp
@@ -163225,6 +171878,11 @@ salt \(aq*\(aq ip.up eth0
Support for Linux LVM2
.INDENT 0.0
.TP
+.B salt.modules.linux_lvm.__virtual__()
+Only load the module if lvm is installed
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.linux_lvm.fullversion()
Return all version info from lvm version
.sp
@@ -163497,6 +172155,11 @@ salt mymachine lvm.vgremove vgname force=True
Module for viewing and modifying sysctl parameters
.INDENT 0.0
.TP
+.B salt.modules.linux_sysctl.__virtual__()
+Only run on Linux systems
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.linux_sysctl.assign(name, value)
Assign a single sysctl parameter for this minion
.sp
@@ -163595,6 +172258,11 @@ salt \(aq*\(aq sysctl.show
Module for managing locales on POSIX\-like systems.
.INDENT 0.0
.TP
+.B salt.modules.localemod.__virtual__()
+Only work on POSIX\-like systems
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.localemod.avail(locale)
Check if a locale is available.
.sp
@@ -163703,6 +172371,11 @@ salt \(aq*\(aq locale.set_locale \(aqen_US.UTF\-8\(aq
Module for using the locate utilities
.INDENT 0.0
.TP
+.B salt.modules.locate.__virtual__()
+Only work on POSIX\-like systems
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.locate.locate(pattern, database=\(aq\(aq, limit=0, **kwargs)
Performs a file lookup. Valid options (and their defaults) are:
.INDENT 7.0
@@ -163795,6 +172468,11 @@ salt \(aq*\(aq locate.version
Module for managing Solaris logadm based log rotations.
.INDENT 0.0
.TP
+.B salt.modules.logadm.__virtual__()
+Only work on Solaris based systems
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.logadm.remove(name, conf_file=\(aq/etc/logadm.conf\(aq)
Remove log pattern from logadm
.sp
@@ -163911,6 +172589,11 @@ Log message at level WARNING.
Module for managing logrotate.
.INDENT 0.0
.TP
+.B salt.modules.logrotate.__virtual__()
+Only work on POSIX\-like systems
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.logrotate.get(key, value=None, conf_file=\(aq/etc/logrotate.conf\(aq)
Get the value for a specific configuration line.
.INDENT 7.0
@@ -164048,6 +172731,11 @@ salt \(aq*\(aq logrotate.show_conf
Support for LVS (Linux Virtual Server)
.INDENT 0.0
.TP
+.B salt.modules.lvs.__virtual__()
+Only load if ipvsadm command exists on the system.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.lvs.add_server(protocol=None, service_address=None, server_address=None, packet_forward_method=\(aqdr\(aq, weight=1, **kwargs)
Add a real server to a virtual service.
.INDENT 7.0
@@ -166803,6 +175491,11 @@ salt \(aq*\(aq assistive.install /usr/bin/osascript
.UNINDENT
.INDENT 0.0
.TP
+.B salt.modules.mac_assistive.__virtual__()
+Only work on Mac OS
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.mac_assistive.enable(app_id, enabled=True)
Enable or disable an existing assistive access application.
.INDENT 7.0
@@ -166939,6 +175632,11 @@ minion, and it is using a different module (or gives an error similar to
.UNINDENT
.INDENT 0.0
.TP
+.B salt.modules.mac_brew.__virtual__()
+Confine this module to Mac OS with Homebrew.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.mac_brew.available_version(*names, **kwargs)
This function is an alias of \fBlatest_version\fP\&.
.INDENT 7.0
@@ -167291,6 +175989,11 @@ salt \(aq*\(aq pkg.version
Set defaults on Mac OS
.INDENT 0.0
.TP
+.B salt.modules.mac_defaults.__virtual__()
+Only work on Mac OS
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.mac_defaults.delete(domain, key, user=None)
Delete a default from the system
.sp
@@ -167391,6 +176094,11 @@ The user to write the defaults to
macOS implementations of various commands in the "desktop" interface
.INDENT 0.0
.TP
+.B salt.modules.mac_desktop.__virtual__()
+Only load on Mac systems
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.mac_desktop.get_output_volume()
Get the output volume (range 0 to 100)
.sp
@@ -167638,6 +176346,11 @@ Install certificates into the keychain on Mac OS
.sp
New in version 2016.3.0.
+.INDENT 0.0
+.TP
+.B salt.modules.mac_keychain.__virtual__()
+Only work on Mac OS
+.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.mac_keychain.get_default_keychain(user=None, domain=\(aquser\(aq)
@@ -167879,6 +176592,11 @@ salt \(aq*\(aq keychain.unlock_keychain /tmp/test.p12 test123
Install pkg, dmg and .app applications on macOS minions.
.INDENT 0.0
.TP
+.B salt.modules.mac_package.__virtual__()
+Only work on Mac OS
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.mac_package.get_mpkg_ids(mpkg)
Attempt to get the package IDs from a mounted .mpkg file
.INDENT 7.0
@@ -168041,12 +176759,8 @@ location of the pkg file inside
\fBdmg\fP (\fI\%str\fP) \-\- The location of the dmg file to mount
.TP
.B Returns
-.INDENT 7.0
-.TP
-.B Tuple containing the results of the command along with the mount
+Tuple containing the results of the command along with the mount
point
-.UNINDENT
-
.TP
.B Return type
\fI\%tuple\fP
@@ -168277,6 +176991,11 @@ In other words \fIsalt mac\-machine pkg.refresh_db\fP is more like
\fIapt\-get update; apt\-get upgrade dpkg apt\-get\fP than simply \fIapt\-get update\fP\&.
.INDENT 0.0
.TP
+.B salt.modules.mac_ports.__virtual__()
+Confine this module to Mac OS with MacPorts.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.mac_ports.available_version(*names, **kwargs)
This function is an alias of \fBlatest_version\fP\&.
.INDENT 7.0
@@ -168623,6 +177342,11 @@ New in version 2016.3.0.
.UNINDENT
.INDENT 0.0
.TP
+.B salt.modules.mac_power.__virtual__()
+Only for macOS
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.mac_power.get_computer_sleep()
Display the amount of idle time until the computer sleeps.
.INDENT 7.0
@@ -168746,10 +177470,11 @@ Computer, Display, and Hard Disk are displayed.
.TP
.B Returns
A dictionary containing the sleep status for Computer, Display, and
-.UNINDENT
-.sp
Hard Disk
-:rtype: dict
+.TP
+.B Return type
+\fI\%dict\fP
+.UNINDENT
.sp
CLI Example:
.INDENT 7.0
@@ -168772,10 +177497,11 @@ supported
.TP
.B Returns
A string value representing the "allow power button to sleep
-.UNINDENT
-.sp
computer" settings
-:rtype: string
+.TP
+.B Return type
+string
+.UNINDENT
.sp
CLI Example:
.INDENT 7.0
@@ -168949,11 +177675,8 @@ functions remains in case they ever fix the bug.
.TP
.B Parameters
\fBenabled\fP (\fI\%bool\fP) \-\- True to enable, False to disable. "On" and "Off" are
-.UNINDENT
-.sp
-also acceptable values. Additionally you can pass 1 and 0 to represent True
-and False respectively
-.INDENT 7.0
+also acceptable values. Additionally you can pass 1 and 0 to represent
+True and False respectively
.TP
.B Returns
True if successful, False if not
@@ -168983,11 +177706,8 @@ failure.
.TP
.B Parameters
\fBenabled\fP (\fI\%bool\fP) \-\- True to enable, False to disable. "On" and "Off" are
-.UNINDENT
-.sp
-also acceptable values. Additionally you can pass 1 and 0 to represent True
-and False respectively
-.INDENT 7.0
+also acceptable values. Additionally you can pass 1 and 0 to represent
+True and False respectively
.TP
.B Returns
True if successful, False if not
@@ -169050,11 +177770,8 @@ Set whether or not the power button can sleep the computer.
.TP
.B Parameters
\fBenabled\fP (\fI\%bool\fP) \-\- True to enable, False to disable. "On" and "Off" are
-.UNINDENT
-.sp
-also acceptable values. Additionally you can pass 1 and 0 to represent True
-and False respectively
-.INDENT 7.0
+also acceptable values. Additionally you can pass 1 and 0 to represent
+True and False respectively
.TP
.B Returns
True if successful, False if not
@@ -169084,11 +177801,8 @@ detected.
.TP
.B Parameters
\fBenabled\fP (\fI\%bool\fP) \-\- True to enable, False to disable. "On" and "Off" are
-.UNINDENT
-.sp
-also acceptable values. Additionally you can pass 1 and 0 to represent True
-and False respectively
-.INDENT 7.0
+also acceptable values. Additionally you can pass 1 and 0 to represent
+True and False respectively
.TP
.B Returns
True if successful, False if not
@@ -169118,11 +177832,8 @@ is detected.
.TP
.B Parameters
\fBenabled\fP (\fI\%bool\fP) \-\- True to enable, False to disable. "On" and "Off" are
-.UNINDENT
-.sp
-also acceptable values. Additionally you can pass 1 and 0 to represent True
-and False respectively
-.INDENT 7.0
+also acceptable values. Additionally you can pass 1 and 0 to represent
+True and False respectively
.TP
.B Returns
True if successful, False if not
@@ -169149,6 +177860,11 @@ The service module for macOS
.. versionadded:: 2016.3.0
.INDENT 0.0
.TP
+.B salt.modules.mac_service.__virtual__()
+Only for macOS with launchctl
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.mac_service.available(name)
Check that the given service is available.
.INDENT 7.0
@@ -169211,7 +177927,7 @@ salt \(aq*\(aq service.disable org.cups.cupsd
.UNINDENT
.INDENT 0.0
.TP
-.B salt.modules.mac_service.disabled(name, runas=None)
+.B salt.modules.mac_service.disabled(name, runas=None, domain=\(aqsystem\(aq)
Check if the specified service is not enabled. This is the opposite of
\fBservice.enabled\fP
.INDENT 7.0
@@ -169222,6 +177938,8 @@ Check if the specified service is not enabled. This is the opposite of
\fBname\fP (\fI\%str\fP) \-\- The name to look up
.IP \(bu 2
\fBrunas\fP (\fI\%str\fP) \-\- User to run launchctl commands
+.IP \(bu 2
+\fBdomain\fP (\fI\%str\fP) \-\- domain to check for disabled services. Default is system.
.UNINDENT
.TP
.B Returns
@@ -169704,10 +178422,10 @@ Get the date/time the account was created
.INDENT 7.0
.TP
.B Parameters
-\fBname\fP (\fI\%str\fP) \-\- the username of the account
+\fBname\fP (\fI\%str\fP) \-\- The username of the account
.TP
.B Returns
-the date/time the account was created (yyyy\-mm\-dd hh:mm:ss)
+The date/time the account was created (yyyy\-mm\-dd hh:mm:ss)
.TP
.B Return type
\fI\%str\fP
@@ -169735,7 +178453,7 @@ Gets the date on which the password expires
.INDENT 7.0
.TP
.B Parameters
-\fBname\fP (\fI\%str\fP) \-\- the name of the user account
+\fBname\fP (\fI\%str\fP) \-\- The name of the user account
.TP
.B Returns
The date the password will expire
@@ -169766,10 +178484,10 @@ Gets the date on which the account expires
.INDENT 7.0
.TP
.B Parameters
-\fBname\fP (\fI\%str\fP) \-\- the name of the user account
+\fBname\fP (\fI\%str\fP) \-\- The name of the user account
.TP
.B Returns
-the date the account expires
+The date the account expires
.TP
.B Return type
\fI\%str\fP
@@ -169797,10 +178515,10 @@ Get the date/time the account was changed
.INDENT 7.0
.TP
.B Parameters
-\fBname\fP (\fI\%str\fP) \-\- the username of the account
+\fBname\fP (\fI\%str\fP) \-\- The username of the account
.TP
.B Returns
-the date/time the account was modified (yyyy\-mm\-dd hh:mm:ss)
+The date/time the account was modified (yyyy\-mm\-dd hh:mm:ss)
.TP
.B Return type
\fI\%str\fP
@@ -169828,7 +178546,7 @@ Get the the number of failed login attempts
.INDENT 7.0
.TP
.B Parameters
-\fBname\fP (\fI\%str\fP) \-\- the username of the account
+\fBname\fP (\fI\%str\fP) \-\- The username of the account
.TP
.B Returns
The number of failed login attempts
@@ -169859,15 +178577,14 @@ Get the date/time of the last failed login attempt
.INDENT 7.0
.TP
.B Parameters
-\fBname\fP (\fI\%str\fP) \-\- the username of the account
+\fBname\fP (\fI\%str\fP) \-\- The username of the account
.TP
.B Returns
-the date/time of the last failed login attempt on this account
-.UNINDENT
-.sp
+The date/time of the last failed login attempt on this account
(yyyy\-mm\-dd hh:mm:ss)
-:rtype: str
-.INDENT 7.0
+.TP
+.B Return type
+\fI\%str\fP
.TP
.B Raises
CommandExecutionError on user not found or any other unknown error
@@ -169892,10 +178609,10 @@ Get the maximum age of the password
.INDENT 7.0
.TP
.B Parameters
-\fBname\fP (\fI\%str\fP) \-\- the username of the account
+\fBname\fP (\fI\%str\fP) \-\- The username of the account
.TP
.B Returns
-the maximum age of the password in days
+The maximum age of the password in days
.TP
.B Return type
\fI\%int\fP
@@ -169923,7 +178640,7 @@ Return information for the specified user
.INDENT 7.0
.TP
.B Parameters
-\fBname\fP (\fI\%str\fP) \-\- the username
+\fBname\fP (\fI\%str\fP) \-\- The username
.TP
.B Returns
A dictionary containing the user\(aqs shadow information
@@ -169954,14 +178671,11 @@ change their password. Format is mm/dd/yyyy
.B Parameters
.INDENT 7.0
.IP \(bu 2
-\fBname\fP (\fI\%str\fP) \-\- the name of the user account
+\fBname\fP (\fI\%str\fP) \-\- The name of the user account
.IP \(bu 2
-\fBdate\fP (\fIdate\fP) \-\- the date the password will expire. Must be in mm/dd/yyyy
-.UNINDENT
-.UNINDENT
-.sp
+\fBdate\fP (\fIdate\fP) \-\- The date the password will expire. Must be in mm/dd/yyyy
format.
-.INDENT 7.0
+.UNINDENT
.TP
.B Returns
True if successful, otherwise False
@@ -169995,14 +178709,11 @@ login after this date. Date format is mm/dd/yyyy
.B Parameters
.INDENT 7.0
.IP \(bu 2
-\fBname\fP (\fI\%str\fP) \-\- the name of the user account
+\fBname\fP (\fI\%str\fP) \-\- The name of the user account
.IP \(bu 2
-\fBdate\fP (\fI\%datetime\fP) \-\- the date the account will expire. Format must be
+\fBdate\fP (\fI\%datetime\fP) \-\- The date the account will expire. Format must be
+mm/dd/yyyy.
.UNINDENT
-.UNINDENT
-.sp
-mm/dd/yyyy
-.INDENT 7.0
.TP
.B Returns
True if successful, False if not
@@ -170069,9 +178780,9 @@ Set the maximum age of the password in days
.B Parameters
.INDENT 7.0
.IP \(bu 2
-\fBname\fP (\fI\%str\fP) \-\- the username of the account
+\fBname\fP (\fI\%str\fP) \-\- The username of the account
.IP \(bu 2
-\fBdays\fP (\fI\%int\fP) \-\- the maximum age of the account in days
+\fBdays\fP (\fI\%int\fP) \-\- The maximum age of the account in days
.UNINDENT
.TP
.B Returns
@@ -170137,14 +178848,13 @@ process list while the command is running)
.INDENT 7.0
.TP
.B Parameters
-\fBname\fP (\fI\%str\fP) \-\- The name of the local user, which is assumed to be in the
-.UNINDENT
-.sp
-local directory service
.INDENT 7.0
-.TP
-.B Parameters
+.IP \(bu 2
+\fBname\fP (\fI\%str\fP) \-\- The name of the local user, which is assumed to be in the
+local directory service
+.IP \(bu 2
\fBpassword\fP (\fI\%str\fP) \-\- The plaintext password to set
+.UNINDENT
.TP
.B Returns
True if successful, otherwise False
@@ -170207,6 +178917,11 @@ salt \(aq*\(aq shadow.set_warndays admin 90
Support for the softwareupdate command on MacOS.
.INDENT 0.0
.TP
+.B salt.modules.mac_softwareupdate.__virtual__()
+Only for MacOS
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.mac_softwareupdate.download(name)
Download a named update so that it can be installed later with the
\fBupdate\fP or \fBupdate_all\fP functions
@@ -170243,18 +178958,14 @@ are now downloaded.
.INDENT 7.0
.TP
.B Parameters
+.INDENT 7.0
+.IP \(bu 2
\fBrecommended\fP (\fI\%bool\fP) \-\- If set to True, only install the recommended
-.UNINDENT
-.sp
updates. If set to False (default) all updates are installed.
-.INDENT 7.0
-.TP
-.B Parameters
+.IP \(bu 2
\fBrestart\fP (\fI\%bool\fP) \-\- Set this to False if you do not want to install updates
-.UNINDENT
-.sp
that require a restart. Default is True
-.INDENT 7.0
+.UNINDENT
.TP
.B Returns
A list containing all downloaded updates on the system.
@@ -170485,13 +179196,12 @@ Enable/disable automatic update scheduling.
.INDENT 7.0
.TP
.B Parameters
-\fBenable\fP \-\- True/On/Yes/1 to turn on automatic updates. False/No/Off/0 to
-.UNINDENT
-.sp
-turn off automatic updates. If this value is empty, the current status will
-be returned.
-:type: bool str
-.INDENT 7.0
+\fBenable\fP \-\- True/On/Yes/1 to turn on automatic updates. False/No/Off/0
+to turn off automatic updates. If this value is empty, the current
+status will be returned.
+.TP
+.B Type
+bool str
.TP
.B Returns
True if scheduling is enabled, False if disabled
@@ -170520,8 +179230,6 @@ Check the status of automatic update scheduling.
.TP
.B Returns
True if scheduling is enabled, False if disabled
-\- \fBTrue\fP: Automatic checking is on,
-\- \fBFalse\fP: Automatic checking is off,
.TP
.B Return type
\fI\%bool\fP
@@ -170606,29 +179314,24 @@ of the update and the status of its installation.
.INDENT 7.0
.TP
.B Parameters
+.INDENT 7.0
+.IP \(bu 2
\fBrecommended\fP (\fI\%bool\fP) \-\- If set to True, only install the recommended
-.UNINDENT
-.sp
updates. If set to False (default) all updates are installed.
-.INDENT 7.0
-.TP
-.B Parameters
+.IP \(bu 2
\fBrestart\fP (\fI\%bool\fP) \-\- Set this to False if you do not want to install updates
-.UNINDENT
-.sp
that require a restart. Default is True
-.INDENT 7.0
+.UNINDENT
.TP
.B Returns
A dictionary containing the updates that were installed and the
+status of its installation. If no updates were installed an empty
+dictionary is returned.
+.TP
+.B Return type
+\fI\%dict\fP
.UNINDENT
.sp
-status of its installation. If no updates were installed an empty dictionary
-is returned.
-:rtype: dict
-\- \fBTrue\fP: The update was installed.
-\- \fBFalse\fP: The update was not installed.
-.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
@@ -170675,6 +179378,11 @@ salt \(aq*\(aq softwareupdate.update_available ""
Module for viewing and modifying sysctl parameters
.INDENT 0.0
.TP
+.B salt.modules.mac_sysctl.__virtual__()
+Only run on Darwin (macOS) systems
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.mac_sysctl.assign(name, value)
Assign a single sysctl parameter for this minion
.INDENT 7.0
@@ -170787,6 +179495,11 @@ Using this module will enable \fBatrun\fP on the system if it is disabled.
.UNINDENT
.INDENT 0.0
.TP
+.B salt.modules.mac_system.__virtual__()
+Only for MacOS with atrun enabled
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.mac_system.get_boot_arch()
Get the kernel architecture setting from \fBcom.apple.Boot.plist\fP
.INDENT 7.0
@@ -170917,10 +179630,11 @@ power failure.
.TP
.B Returns
A string value representing the number of seconds the system will
-.UNINDENT
-.sp
delay restart after power loss
-:rtype: str
+.TP
+.B Return type
+\fI\%str\fP
+.UNINDENT
.sp
CLI Example:
.INDENT 7.0
@@ -170991,20 +179705,34 @@ Halt a running system
.INDENT 7.0
.TP
.B Parameters
-\fBat_time\fP (\fI\%str\fP) \-\- Any valid \fIat\fP expression. For example, some valid at
+\fBat_time\fP (\fI\%str\fP) \-\-
+.sp
+Any valid \fIat\fP expression. For example, some valid at
+expressions could be:
+.INDENT 7.0
+.IP \(bu 2
+noon
+.IP \(bu 2
+midnight
+.IP \(bu 2
+fri
+.IP \(bu 2
+9:00 AM
+.IP \(bu 2
+2:30 PM tomorrow
+.IP \(bu 2
+now + 10 minutes
+.UNINDENT
+
.UNINDENT
.sp
-expressions could be:
-\- noon
-\- midnight
-\- fri
-\- 9:00 AM
-\- 2:30 PM tomorrow
-\- now + 10 minutes
-.sp
-Note::
-If you pass a time only, with no \(aqAM/PM\(aq designation, you have to double
-quote the parameter on the command line. For example: \(aq"14:00"\(aq
+\fBNOTE:\fP
+.INDENT 7.0
+.INDENT 3.5
+If you pass a time only, with no \(aqAM/PM\(aq designation, you have to
+double quote the parameter on the command line. For example: \(aq"14:00"\(aq
+.UNINDENT
+.UNINDENT
.sp
CLI Example:
.INDENT 7.0
@@ -171051,20 +179779,34 @@ Restart the system
.INDENT 7.0
.TP
.B Parameters
-\fBat_time\fP (\fI\%str\fP) \-\- Any valid \fIat\fP expression. For example, some valid at
+\fBat_time\fP (\fI\%str\fP) \-\-
+.sp
+Any valid \fIat\fP expression. For example, some valid at
+expressions could be:
+.INDENT 7.0
+.IP \(bu 2
+noon
+.IP \(bu 2
+midnight
+.IP \(bu 2
+fri
+.IP \(bu 2
+9:00 AM
+.IP \(bu 2
+2:30 PM tomorrow
+.IP \(bu 2
+now + 10 minutes
+.UNINDENT
+
.UNINDENT
.sp
-expressions could be:
-\- noon
-\- midnight
-\- fri
-\- 9:00 AM
-\- 2:30 PM tomorrow
-\- now + 10 minutes
-.sp
-Note::
-If you pass a time only, with no \(aqAM/PM\(aq designation, you have to double
-quote the parameter on the command line. For example: \(aq"14:00"\(aq
+\fBNOTE:\fP
+.INDENT 7.0
+.INDENT 3.5
+If you pass a time only, with no \(aqAM/PM\(aq designation, you have to
+double quote the parameter on the command line. For example: \(aq"14:00"\(aq
+.UNINDENT
+.UNINDENT
.sp
CLI Example:
.INDENT 7.0
@@ -171087,26 +179829,28 @@ Set the kernel to boot in 32 or 64 bit mode on next boot.
\fBNOTE:\fP
.INDENT 7.0
.INDENT 3.5
-This command fails with the following error:
-.sp
-\fBchanges to kernel architecture failed to save!\fP
-.sp
-The setting is not updated. This is either an apple bug, not available
-on the test system, or a result of system files now being locked down in
-macOS (SIP Protection).
+When this function fails with the error \fBchanges to kernel
+architecture failed to save!\fP, then the boot arch is not updated.
+This is either an Apple bug, not available on the test system, or a
+result of system files being locked down in macOS (SIP Protection).
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B Parameters
-\fBarch\fP (\fI\%str\fP) \-\- A string representing the desired architecture. If no
-.UNINDENT
+\fBarch\fP (\fI\%str\fP) \-\-
.sp
+A string representing the desired architecture. If no
value is passed, default is assumed. Valid values include:
-\- i386
-\- x86_64
-\- default
.INDENT 7.0
+.IP \(bu 2
+i386
+.IP \(bu 2
+x86_64
+.IP \(bu 2
+default
+.UNINDENT
+
.TP
.B Returns
True if successful, False if not
@@ -171164,11 +179908,8 @@ enclosure lock is engaged.
.TP
.B Parameters
\fBenable\fP (\fI\%bool\fP) \-\- True to enable, False to disable. "On" and "Off" are
-.UNINDENT
-.sp
-also acceptable values. Additionally you can pass 1 and 0 to represent True
-and False respectively
-.INDENT 7.0
+also acceptable values. Additionally you can pass 1 and 0 to represent
+True and False respectively
.TP
.B Returns
True if successful, False if not
@@ -171198,11 +179939,8 @@ AppleScripts)
.TP
.B Parameters
\fBenable\fP (\fI\%bool\fP) \-\- True to enable, False to disable. "On" and "Off" are
-.UNINDENT
-.sp
-also acceptable values. Additionally you can pass 1 and 0 to represent True
-and False respectively
-.INDENT 7.0
+also acceptable values. Additionally you can pass 1 and 0 to represent
+True and False respectively
.TP
.B Returns
True if successful, False if not
@@ -171231,11 +179969,8 @@ Set the remote login (SSH) to either on or off.
.TP
.B Parameters
\fBenable\fP (\fI\%bool\fP) \-\- True to enable, False to disable. "On" and "Off" are
-.UNINDENT
-.sp
-also acceptable values. Additionally you can pass 1 and 0 to represent True
-and False respectively
-.INDENT 7.0
+also acceptable values. Additionally you can pass 1 and 0 to represent
+True and False respectively
.TP
.B Returns
True if successful, False if not
@@ -171374,20 +180109,34 @@ Shutdown the system
.INDENT 7.0
.TP
.B Parameters
-\fBat_time\fP (\fI\%str\fP) \-\- Any valid \fIat\fP expression. For example, some valid at
+\fBat_time\fP (\fI\%str\fP) \-\-
+.sp
+Any valid \fIat\fP expression. For example, some valid at
+expressions could be:
+.INDENT 7.0
+.IP \(bu 2
+noon
+.IP \(bu 2
+midnight
+.IP \(bu 2
+fri
+.IP \(bu 2
+9:00 AM
+.IP \(bu 2
+2:30 PM tomorrow
+.IP \(bu 2
+now + 10 minutes
+.UNINDENT
+
.UNINDENT
.sp
-expressions could be:
-\- noon
-\- midnight
-\- fri
-\- 9:00 AM
-\- 2:30 PM tomorrow
-\- now + 10 minutes
-.sp
-Note::
-If you pass a time only, with no \(aqAM/PM\(aq designation, you have to double
-quote the parameter on the command line. For example: \(aq"14:00"\(aq
+\fBNOTE:\fP
+.INDENT 7.0
+.INDENT 3.5
+If you pass a time only, with no \(aqAM/PM\(aq designation, you have to
+double quote the parameter on the command line. For example: \(aq"14:00"\(aq
+.UNINDENT
+.UNINDENT
.sp
CLI Example:
.INDENT 7.0
@@ -171410,20 +180159,34 @@ sleep.
.INDENT 7.0
.TP
.B Parameters
-\fBat_time\fP (\fI\%str\fP) \-\- Any valid \fIat\fP expression. For example, some valid at
+\fBat_time\fP (\fI\%str\fP) \-\-
+.sp
+Any valid \fIat\fP expression. For example, some valid at
+expressions could be:
+.INDENT 7.0
+.IP \(bu 2
+noon
+.IP \(bu 2
+midnight
+.IP \(bu 2
+fri
+.IP \(bu 2
+9:00 AM
+.IP \(bu 2
+2:30 PM tomorrow
+.IP \(bu 2
+now + 10 minutes
+.UNINDENT
+
.UNINDENT
.sp
-expressions could be:
-\- noon
-\- midnight
-\- fri
-\- 9:00 AM
-\- 2:30 PM tomorrow
-\- now + 10 minutes
-.sp
-Note::
-If you pass a time only, with no \(aqAM/PM\(aq designation, you have to double
-quote the parameter on the command line. For example: \(aq"14:00"\(aq
+\fBNOTE:\fP
+.INDENT 7.0
+.INDENT 3.5
+If you pass a time only, with no \(aqAM/PM\(aq designation, you have to
+double quote the parameter on the command line. For example: \(aq"14:00"\(aq
+.UNINDENT
+.UNINDENT
.sp
CLI Example:
.INDENT 7.0
@@ -171449,6 +180212,11 @@ New in version 2016.3.0.
.UNINDENT
.INDENT 0.0
.TP
+.B salt.modules.mac_timezone.__virtual__()
+Only for macOS
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.mac_timezone.get_date()
Displays the current date
.INDENT 7.0
@@ -171672,8 +180440,9 @@ Set the current month, day, and year
.INDENT 7.0
.TP
.B Parameters
-\fBdate\fP (\fI\%str\fP) \-\- The date to set. Valid date formats are:
-.UNINDENT
+\fBdate\fP (\fI\%str\fP) \-\-
+.sp
+The date to set. Valid date formats are:
.INDENT 7.0
.IP \(bu 2
%m:%d:%y
@@ -171684,7 +180453,7 @@ Set the current month, day, and year
.IP \(bu 2
%m/%d/%Y
.UNINDENT
-.INDENT 7.0
+
.TP
.B Returns
True if successful, False if not
@@ -171735,11 +180504,8 @@ Sets the current time. Must be in 24 hour format.
.INDENT 7.0
.TP
.B Parameters
-\fBtime\fP (\fI\%str\fP) \-\- The time to set in 24 hour format.
-.UNINDENT
-.sp
-The value must be double quoted. ie: \(aq"17:46"\(aq
-.INDENT 7.0
+\fBtime\fP (\fI\%str\fP) \-\- The time to set in 24 hour format. The value must be
+double quoted. ie: \(aq"17:46"\(aq
.TP
.B Returns
True if successful, False if not
@@ -171774,12 +180540,12 @@ network time server.
.INDENT 7.0
.TP
.B Parameters
-\fBtime_server\fP \-\- IP or DNS name of the network time server. If nothing is
-.UNINDENT
-.sp
-passed the time server will be set to the macOS default of \(aqtime.apple.com\(aq
-:type: str
-.INDENT 7.0
+\fBtime_server\fP \-\- IP or DNS name of the network time server. If nothing
+is passed the time server will be set to the macOS default of
+\(aqtime.apple.com\(aq
+.TP
+.B Type
+str
.TP
.B Returns
True if successful, False if not
@@ -172287,6 +181053,11 @@ salt \(aq*\(aq xattr.list /path/to/file
.UNINDENT
.INDENT 0.0
.TP
+.B salt.modules.mac_xattr.__virtual__()
+Only work on Mac OS
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.mac_xattr.clear(path)
Causes the all attributes on the file/directory to be removed
.INDENT 7.0
@@ -172325,11 +181096,8 @@ Removes the given attribute from the file
\fBpath\fP (\fI\%str\fP) \-\- The file(s) to get attributes from
.IP \(bu 2
\fBattribute\fP (\fI\%str\fP) \-\- The attribute name to be deleted from the
-.UNINDENT
-.UNINDENT
-.sp
file/directory
-.INDENT 7.0
+.UNINDENT
.TP
.B Returns
True if successful, otherwise False
@@ -172339,9 +181107,8 @@ True if successful, otherwise False
.TP
.B Raises
CommandExecutionError on file not found, attribute not found, and
-.UNINDENT
-.sp
any other unknown error
+.UNINDENT
.sp
CLI Example:
.INDENT 7.0
@@ -172371,11 +181138,10 @@ List all of the extended attributes on the given file/directory
.TP
.B Returns
A dictionary containing extended attributes and values for the
-.UNINDENT
-.sp
given file
-:rtype: dict
-.INDENT 7.0
+.TP
+.B Return type
+\fI\%dict\fP
.TP
.B Raises
CommandExecutionError on file not found or any other unknown error
@@ -172418,9 +181184,8 @@ A string containing the value of the named attribute
.TP
.B Raises
CommandExecutionError on file not found, attribute not found, and
-.UNINDENT
-.sp
any other unknown error
+.UNINDENT
.sp
CLI Example:
.INDENT 7.0
@@ -172480,6 +181245,11 @@ salt \(aq*\(aq xattr.write /path/to/file "com.test.attr" "value"
Support for modifying make.conf under Gentoo
.INDENT 0.0
.TP
+.B salt.modules.makeconf.__virtual__()
+Only work on Gentoo
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.makeconf.append_cflags(value)
Add to or create a new CFLAGS in the make.conf
.sp
@@ -174079,6 +182849,16 @@ mattermost:
.UNINDENT
.INDENT 0.0
.TP
+.B salt.modules.mattermost.__virtual__()
+Return virtual name of the module.
+.INDENT 7.0
+.TP
+.B Returns
+The virtual name of the module.
+.UNINDENT
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.mattermost.post_message(message, channel=None, username=None, api_url=None, hook=None)
Send a message to a Mattermost channel.
.INDENT 7.0
@@ -174107,7 +182887,7 @@ CLI Example:
.sp
.nf
.ft C
-salt \(aq*\(aq mattermost.post_message message=\(aqBuild is done"
+salt \(aq*\(aq mattermost.post_message message=\(aqBuild is done\(aq
.ft P
.fi
.UNINDENT
@@ -174118,6 +182898,11 @@ salt \(aq*\(aq mattermost.post_message message=\(aqBuild is done"
Salt module to manage RAID arrays with mdadm
.INDENT 0.0
.TP
+.B salt.modules.mdadm.__virtual__()
+mdadm provides raid functions for Linux
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.mdadm.assemble(name, devices, test_mode=False, **kwargs)
Assemble a RAID device.
.sp
@@ -174360,6 +183145,11 @@ smartos
.UNINDENT
.INDENT 0.0
.TP
+.B salt.modules.mdata.__virtual__()
+Provides mdata only on SmartOS
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.mdata.delete(*keyname)
Delete metadata
.INDENT 7.0
@@ -174463,6 +183253,11 @@ Module for Management of Memcached Keys
.sp
New in version 2014.1.0.
+.INDENT 0.0
+.TP
+.B salt.modules.memcached.__virtual__()
+Only load if python\-memcache is installed
+.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.memcached.add(key, value, host=\(aq127.0.0.1\(aq, port=11211, time=0, min_compress_len=0)
@@ -174716,10 +183511,19 @@ example:
.INDENT 0.0
.TP
.B salt.modules.mine.get_docker(interfaces=None, cidrs=None, with_container_id=False)
-Get all mine data for \(aqdocker.get_containers\(aq and run an aggregation
-routine. The "interfaces" parameter allows for specifying which network
-interfaces to select ip addresses from. The "cidrs" parameter allows for
-specifying a list of cidrs which the ip address must match.
+Changed in version 2017.7.8,2018.3.3: When \fBdocker.update_mine\fP is set to \fBFalse\fP for a given
+minion, no mine data will be populated for that minion, and thus none
+will be returned for it.
+
+.sp
+Changed in version Fluorine: \fBdocker.update_mine\fP now defaults to \fBFalse\fP
+
+.sp
+Get all mine data for \fBdocker.ps\fP and
+run an aggregation routine. The \fBinterfaces\fP parameter allows for
+specifying the network interfaces from which to select IP addresses. The
+\fBcidrs\fP parameter allows for specifying a list of subnets which the IP
+address must match.
.INDENT 7.0
.TP
.B with_container_id
@@ -174989,6 +183793,11 @@ information in the \fBcomment\fP field as is demonstrated with \fBminion2\fP\&.
.sp
New in version 2014.7.0.
+.INDENT 0.0
+.TP
+.B salt.modules.mod_random.__virtual__(algorithm=\(aqsha512\(aq)
+Sanity check for compatibility with Python 2.6 / 2.7
+.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.mod_random.get_str(length=20)
@@ -175195,6 +184004,11 @@ modjk:
.UNINDENT
.INDENT 0.0
.TP
+.B salt.modules.modjk.__virtual__()
+Always load
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.modjk.bulk_activate(workers, lbn, profile=\(aqdefault\(aq)
Activate all the given workers in the specific load balancer
.sp
@@ -175563,6 +184377,11 @@ overwrite options passed into pillar.
.UNINDENT
.INDENT 0.0
.TP
+.B salt.modules.mongodb.__virtual__()
+Only load this module if pymongo is installed
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.mongodb.db_exists(name, user=None, password=None, host=None, port=None, authdb=None)
Checks if a database exists in Mongodb
.sp
@@ -176101,6 +184920,11 @@ salt \(aq*\(aq monit.version
Module for gathering and managing information about MooseFS
.INDENT 0.0
.TP
+.B salt.modules.moosefs.__virtual__()
+Only load if the mfs commands are installed
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.moosefs.dirinfo(path, opts=None)
Return information on a directory located on the Moose
.sp
@@ -176173,6 +184997,11 @@ salt \(aq*\(aq moosefs.mounts
Salt module to manage Unix mounts and the fstab file
.INDENT 0.0
.TP
+.B salt.modules.mount.__virtual__()
+Only load on POSIX\-like systems
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.mount.active(extended=False)
List the active mounts.
.sp
@@ -176558,6 +185387,11 @@ configs or pillars.
.UNINDENT
.INDENT 0.0
.TP
+.B salt.modules.mssql.__virtual__()
+Only load this module if all imports succeeded bin exists
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.mssql.db_exists(database_name, **kwargs)
Find if a specific database exists on the MS SQL server.
.sp
@@ -176808,24 +185642,32 @@ salt minion mssql.version
.SS salt.modules.msteams module
.sp
Module for sending messages to MS Teams
-.. versionadded:: 2017.7.0
-:configuration: This module can be used by either passing a hook_url
-.INDENT 0.0
-.INDENT 3.5
-directly or by specifying it in a configuration profile in the salt
-master/minion config.
-For example:
-.. code\-block:: yaml
-.INDENT 0.0
-.INDENT 3.5
+.sp
+New in version 2017.7.0.
+
.INDENT 0.0
.TP
-.B msteams:
-hook_url: \fI\%https://outlook.office.com/webhook/837\fP
-.UNINDENT
-.UNINDENT
+.B configuration
+This module can be used by either passing a hook_url
+directly or by specifying it in a configuration profile in the salt
+master/minion config. For example:
+.UNINDENT
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+msteams:
+ hook_url: https://outlook.office.com/webhook/837
+.ft P
+.fi
.UNINDENT
.UNINDENT
+.INDENT 0.0
+.TP
+.B salt.modules.msteams.__virtual__()
+Return virtual name of the module.
+:return: The virtual name of the module.
.UNINDENT
.INDENT 0.0
.TP
@@ -176836,11 +185678,16 @@ Send a message to an MS Teams channel.
:param title: Optional title for the posted card
:param theme_color: Optional hex color highlight for the posted card
:return: Boolean if message was sent successfully.
+.sp
CLI Example:
-.. code\-block:: bash
.INDENT 7.0
.INDENT 3.5
+.sp
+.nf
+.ft C
salt \(aq*\(aq msteams.post_card message="Build is done"
+.ft P
+.fi
.UNINDENT
.UNINDENT
.UNINDENT
@@ -176849,6 +185696,11 @@ salt \(aq*\(aq msteams.post_card message="Build is done"
Run munin plugins/checks from salt and format the output as data.
.INDENT 0.0
.TP
+.B salt.modules.munin.__virtual__()
+Only load the module if munin\-node is installed
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.munin.list_plugins()
List all the munin plugins
.sp
@@ -176961,6 +185813,11 @@ Changed in version 0.16.2: Connection arguments from the minion config file can
CLI by using the arguments defined \fBhere\fP\&.
Additionally, it is now possible to setup a user with no password.
+.INDENT 0.0
+.TP
+.B salt.modules.mysql.__virtual__()
+Only load this module if the mysql libraries exist
+.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.mysql.alter_db(name, character_set=None, collate=None, **connection_args)
@@ -178107,6 +186964,11 @@ salt\-call \-\-local \-\-out=newline_values_only nacl.keygen > /root/.nacl
Run nagios plugins/checks from salt and get the return as data.
.INDENT 0.0
.TP
+.B salt.modules.nagios.__virtual__()
+Only load if nagios\-plugins are installed
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.nagios.list_plugins()
List all the nagios plugins
.sp
@@ -178283,6 +187145,11 @@ Check Host & Service status from Nagios via JSON RPC.
.sp
New in version 2015.8.0.
+.INDENT 0.0
+.TP
+.B salt.modules.nagios_rpc.__virtual__()
+Only load if requests is successfully imported
+.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.nagios_rpc.host_status(hostname=None, **kwargs)
@@ -178358,38 +187225,19 @@ salt \(aq*\(aq nagios_rpc.service_status hostname=webserver.domain.com service=\
.UNINDENT
.SS salt.modules.namecheap_dns module
.sp
-Use this module to manage dns through the namecheap
-api. The Namecheap settings will be set in grains.
-.INDENT 0.0
-.IP \(bu 2
-This module uses the following python libraries to communicate to
-the namecheap API:
-.INDENT 2.0
-.INDENT 3.5
-.INDENT 0.0
-.IP \(bu 2
-\fBrequests\fP
-.UNINDENT
-.INDENT 0.0
-.INDENT 3.5
+Namecheap DNS Management
.sp
-.nf
-.ft C
-pip install requests
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.UNINDENT
-.UNINDENT
-.IP \(bu 2
-As saltstack depends on \fBrequests\fP this shouldn\(aqt be a problem
-.UNINDENT
+New in version 2017.7.0.
+
+.SS Prerequisites
+.sp
+This module uses the \fBrequests\fP Python module to communicate to the namecheap
+API.
+.SS Configuration
+.sp
+The Namecheap username, API key and URL should be set in the minion configuration
+file, or in the Pillar data.
.INDENT 0.0
-.IP \(bu 2
-The namecheap username, api key and url should be set in a minion
-configuration file or pillar
-.INDENT 2.0
.INDENT 3.5
.sp
.nf
@@ -178405,8 +187253,11 @@ namecheap.url: https://api.namecheap.com/xml.response
.fi
.UNINDENT
.UNINDENT
+.INDENT 0.0
+.TP
+.B salt.modules.namecheap_dns.__virtual__()
+Check to make sure requests and xml are installed and requests
.UNINDENT
-
.INDENT 0.0
.TP
.B salt.modules.namecheap_dns.get_hosts(sld, tld)
@@ -178416,10 +187267,10 @@ returns a dictionary of information about the requested domain
.INDENT 7.0
.TP
.B sld
-string sld of the domainname
+SLD of the domain name
.TP
.B tld
-string tld of the domainname
+TLD of the domain name
.UNINDENT
.sp
CLI Example:
@@ -178443,10 +187294,10 @@ returns a dictionary of information about requested domain
.INDENT 7.0
.TP
.B sld
-string sld of the domainname
+SLD of the domain name
.TP
.B tld
-string tld of the domain name
+TLD of the domain name
.UNINDENT
.sp
CLI Example:
@@ -178470,10 +187321,10 @@ returns True if the custom nameservers were set successfully
.INDENT 7.0
.TP
.B sld
-string sld of the domainname
+SLD of the domain name
.TP
.B tld
-string tld of the domain name
+TLD of the domain name
.TP
.B nameservers
array of strings List of nameservers to be associated with this domain
@@ -178494,20 +187345,21 @@ salt \(aqmy\-minion\(aq namecheap_domains_dns.set_custom sld tld nameserver
.INDENT 0.0
.TP
.B salt.modules.namecheap_dns.set_default(sld, tld)
-Sets domain to use namecheap default DNS servers.
-Required for free services like Host record management,
-URL forwarding, email forwarding, dynamic dns and other value added services.
-.sp
-returns True if the domain was set to default
+Sets domain to use namecheap default DNS servers. Required for free
+services like Host record management, URL forwarding, email forwarding,
+dynamic DNS and other value added services.
.INDENT 7.0
.TP
.B sld
-string sld of the domainname
+SLD of the domain name
.TP
.B tld
-string tld of the domain name
+TLD of the domain name
.UNINDENT
.sp
+Returns \fBTrue\fP if the domain was successfully pointed at the default DNS
+servers.
+.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
@@ -178529,24 +187381,28 @@ returns True if the host records were set successfully
.INDENT 7.0
.TP
.B sld
-string sld of the domainname
+SLD of the domain name
.TP
.B tld
-string tld of the domain name
+TLD of the domain name
.TP
.B hosts
+Must be passed as a list of Python dictionaries, with each dictionary
+containing the following keys:
.INDENT 7.0
-.TP
-.B array of dictionaries each dictionary should contain the following keys:
-\(aqhostname\(aq, \(aqrecordtype\(aq, and \(aqaddress\(aq
-\(aqttl\(aq is optional, Default value is 1800
-\(aqmxpref\(aq is optional but must be included with \(aqemailtype\(aq
-.sp
-\(aqhostname\(aq should be the subdomain/hostname
-\(aqrecordtype\(aq should be A,AAAA,CNAME,MX,MXE,TXT,URL,URL301,FRAME
-\(aqaddress\(aq should be url or ip address
-\(aqttl\(aq should be an integer between 60 to 60000
+.IP \(bu 2
+\fBhostname\fP
+.IP \(bu 2
+\fBrecordtype\fP \- One of \fBA\fP, \fBAAAA\fP, \fBCNAME\fP, \fBMX\fP, \fBMXE\fP,
+\fBTXT\fP, \fBURL\fP, \fBURL301\fP, or \fBFRAME\fP
+.IP \(bu 2
+\fBaddress\fP \- URL or IP address
+.IP \(bu 2
+\fBttl\fP \- An integer between 60 and 60000 (default: \fB1800\fP)
.UNINDENT
+.sp
+Additonally, the \fBmxpref\fP key can be present, but must be accompanied
+by an \fBemailtype\fP key.
.UNINDENT
.sp
CLI Example:
@@ -178563,46 +187419,19 @@ salt \(aqmy\-minion\(aq namecheap_domains_dns.set_hosts sld tld hosts
.UNINDENT
.SS salt.modules.namecheap_domains module
.sp
-Namecheap management
+Namecheap Domain Management
.sp
New in version 2017.7.0.
-.SS General Notes
+.SS Prerequisites
.sp
-Use this module to manage domains through the namecheap
-api. The Namecheap settings will be set in grains.
-.SS Installation Prerequisites
-.INDENT 0.0
-.IP \(bu 2
-This module uses the following python libraries to communicate to
-the namecheap API:
-.INDENT 2.0
-.INDENT 3.5
-.INDENT 0.0
-.IP \(bu 2
-\fBrequests\fP
-.UNINDENT
-.INDENT 0.0
-.INDENT 3.5
+This module uses the \fBrequests\fP Python module to communicate to the namecheap
+API.
+.SS Configuration
.sp
-.nf
-.ft C
-pip install requests
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.UNINDENT
-.UNINDENT
-.IP \(bu 2
-As saltstack depends on \fBrequests\fP this shouldn\(aqt be a problem
-.UNINDENT
-.SS Prerequisite Configuration
+The Namecheap username, API key and URL should be set in the minion configuration
+file, or in the Pillar data.
.INDENT 0.0
-.IP \(bu 2
-The namecheap username, api key and url should be set in a minion
-configuration file or pillar
-.INDENT 2.0
.INDENT 3.5
.sp
.nf
@@ -178618,6 +187447,10 @@ namecheap.url: https://api.namecheap.com/xml.response
.fi
.UNINDENT
.UNINDENT
+.INDENT 0.0
+.TP
+.B salt.modules.namecheap_domains.__virtual__()
+Check to make sure requests and xml are installed and requests
.UNINDENT
.INDENT 0.0
.TP
@@ -178625,13 +187458,13 @@ namecheap.url: https://api.namecheap.com/xml.response
Checks the availability of domains
.INDENT 7.0
.TP
-.B returns a dictionary where the domain name is the key and
-the availability is the value of True/False
-.TP
.B domains_to_check
array of strings List of domains to check
.UNINDENT
.sp
+Returns a dictionary mapping the each domain name to a boolean denoting
+whether or not it is available.
+.sp
CLI Example:
.INDENT 7.0
.INDENT 3.5
@@ -178647,17 +187480,32 @@ salt \(aqmy\-minion\(aq namecheap_domains.check domain\-to\-check
.INDENT 0.0
.TP
.B salt.modules.namecheap_domains.create(domain_name, years, **kwargs)
-Try to create the specified domain name for the specified number of years
+Try to register the specified domain name
.INDENT 7.0
.TP
-.B returns the following information in a dictionary
-registered True/False
-amount charged for registration
-domainid unique integer value for the domain
-orderid unique integer value for the order
-transactionid unique integer value for the transaction
-whoisguardenable True,False if enabled for this domain
-nonrealtimedomain True,False if domain registration is instant or not
+.B domain_name
+The domain name to be registered
+.TP
+.B years
+Number of years to register
+.UNINDENT
+.sp
+Returns the following information:
+.INDENT 7.0
+.IP \(bu 2
+Whether or not the domain was renewed successfully
+.IP \(bu 2
+Whether or not WhoisGuard is enabled
+.IP \(bu 2
+Whether or not registration is instant
+.IP \(bu 2
+The amount charged for registration
+.IP \(bu 2
+The domain ID
+.IP \(bu 2
+The order ID
+.IP \(bu 2
+The transaction ID
.UNINDENT
.sp
CLI Example:
@@ -178704,36 +187552,24 @@ offset by \fBpage\fP length of \fBpage_size\fP
.INDENT 7.0
.TP
.B list_type
-.INDENT 7.0
-.TP
-.B string Possible values are ALL/EXPIRING/EXPIRED
-Default: ALL
-.UNINDENT
+ALL
+One of \fBALL\fP, \fBEXPIRING\fP, \fBEXPIRED\fP
.TP
.B search_term
-string Keyword to look for on the domain list
+Keyword to look for on the domain list
.TP
.B page
-.INDENT 7.0
-.TP
-.B integer Page to return
-Default: 1
-.UNINDENT
+1
+Number of result page to return
.TP
.B page_size
-.INDENT 7.0
-.TP
-.B integer Number of domains to be listed in a page
-Minimum value is 10 and maximum value is 100
-Default: 20
-.UNINDENT
+20
+Number of domains to be listed per page (minimum: \fB10\fP, maximum:
+\fB100\fP)
.TP
.B sort_by
-.INDENT 7.0
-.TP
-.B string Possible values are NAME/NAME_DESC/EXPIREDATE/
-EXPIREDATE_DESC/CREATEDATE/CREATEDATE_DESC
-.UNINDENT
+One of \fBNAME\fP, \fBNAME_DESC\fP, \fBEXPIREDATE\fP, \fBEXPIREDATE_DESC\fP,
+\fBCREATEDATE\fP, or \fBCREATEDATE_DESC\fP
.UNINDENT
.sp
CLI Example:
@@ -178769,16 +187605,30 @@ salt \(aqmy\-minion\(aq namecheap_domains.get_tld_list
.TP
.B salt.modules.namecheap_domains.reactivate(domain_name)
Try to reactivate the expired domain name
+.sp
+Returns the following information:
.INDENT 7.0
-.TP
-.B returns the following information in a dictionary
-issuccess bool indicates whether the domain was renewed successfully
-amount charged for reactivation
-orderid unique integer value for the order
-transactionid unique integer value for the transaction
+.IP \(bu 2
+Whether or not the domain was reactivated successfully
+.IP \(bu 2
+The amount charged for reactivation
+.IP \(bu 2
+The order ID
+.IP \(bu 2
+The transaction ID
.UNINDENT
.sp
CLI Example:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+salt \(aqmy\-minion\(aq namecheap_domains.reactivate my\-domain\-name
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
@@ -178786,19 +187636,25 @@ CLI Example:
Try to renew the specified expiring domain name for a specified number of years
.INDENT 7.0
.TP
-.B returns the following information in a dictionary
-renew bool indicates whether the domain was renewed successfully
-domainid unique integer value for the domain
-orderid unique integer value for the order
-transactionid unique integer value for the transaction
-amount charged for renewal
-.TP
-.B Required parameters:
-.INDENT 7.0
-.TP
.B domain_name
-string The domain name you wish to renew
+The domain name to be renewed
+.TP
+.B years
+Number of years to renew
.UNINDENT
+.sp
+Returns the following information:
+.INDENT 7.0
+.IP \(bu 2
+Whether or not the domain was renewed successfully
+.IP \(bu 2
+The domain ID
+.IP \(bu 2
+The order ID
+.IP \(bu 2
+The transaction ID
+.IP \(bu 2
+The amount charged for renewal
.UNINDENT
.sp
CLI Example:
@@ -178815,38 +187671,19 @@ salt \(aqmy\-minion\(aq namecheap_domains.renew my\-domain\-name 5
.UNINDENT
.SS salt.modules.namecheap_ns module
.sp
-Use this module to manage nameservers through the namecheap
-api. The Namecheap settings will be set in grains.
-.INDENT 0.0
-.IP \(bu 2
-This module uses the following python libraries to communicate to
-the namecheap API:
-.INDENT 2.0
-.INDENT 3.5
-.INDENT 0.0
-.IP \(bu 2
-\fBrequests\fP
-.UNINDENT
-.INDENT 0.0
-.INDENT 3.5
+Namecheap Nameserver Management
.sp
-.nf
-.ft C
-pip install requests
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.UNINDENT
-.UNINDENT
-.IP \(bu 2
-As saltstack depends on \fBrequests\fP this shouldn\(aqt be a problem
-.UNINDENT
+New in version 2017.7.0.
+
+.SS Prerequisites
+.sp
+This module uses the \fBrequests\fP Python module to communicate to the namecheap
+API.
+.SS Configuration
+.sp
+The Namecheap username, API key and URL should be set in the minion configuration
+file, or in the Pillar data.
.INDENT 0.0
-.IP \(bu 2
-The namecheap username, api key and url should be set in a minion
-configuration file or pillar
-.INDENT 2.0
.INDENT 3.5
.sp
.nf
@@ -178862,27 +187699,29 @@ namecheap.url: https://api.namecheap.com/xml.response
.fi
.UNINDENT
.UNINDENT
+.INDENT 0.0
+.TP
+.B salt.modules.namecheap_ns.__virtual__()
+Check to make sure requests and xml are installed and requests
.UNINDENT
-
.INDENT 0.0
.TP
.B salt.modules.namecheap_ns.create(sld, tld, nameserver, ip)
-Creates a new nameserver
-.sp
-returns True if the nameserver was created successfully
+Creates a new nameserver. Returns \fBTrue\fP if the nameserver was created
+successfully.
.INDENT 7.0
.TP
.B sld
-string SLD of the DomainName
+SLD of the domain name
.TP
.B tld
-string TLD of the DomainName
+TLD of the domain name
.TP
.B nameserver
-string Nameserver to create
+Nameserver to create
.TP
.B ip
-string Nameserver IP address
+Nameserver IP address
.UNINDENT
.sp
CLI Example:
@@ -178900,19 +187739,18 @@ salt \(aq*\(aq namecheap_domains_ns.create sld tld nameserver ip
.INDENT 0.0
.TP
.B salt.modules.namecheap_ns.delete(sld, tld, nameserver)
-Deletes a nameserver
-.sp
-returns True if the nameserver was deleted successfully
+Deletes a nameserver. Returns \fBTrue\fP if the nameserver was deleted
+successfully
.INDENT 7.0
.TP
.B sld
-string SLD of the DomainName
+SLD of the domain name
.TP
.B tld
-string TLD of the DomainName
+TLD of the domain name
.TP
.B nameserver
-string Nameserver to create
+Nameserver to delete
.UNINDENT
.sp
CLI Example:
@@ -178930,22 +187768,26 @@ salt \(aq*\(aq namecheap_domains_ns.delete sld tld nameserver
.INDENT 0.0
.TP
.B salt.modules.namecheap_ns.get_info(sld, tld, nameserver)
-Retrieves information about a registered nameserver
+Retrieves information about a registered nameserver. Returns the following
+information:
+.INDENT 7.0
+.IP \(bu 2
+IP Address set for the nameserver
+.IP \(bu 2
+Domain name which was queried
+.IP \(bu 2
+A list of nameservers and their statuses
+.UNINDENT
.INDENT 7.0
.TP
-.B returns the following information in a dictionary
-ipaddress set for the nameserver
-domain name for which you are trying to get nameserver details
-status an array of status about the nameservers
-.TP
.B sld
-string SLD of the DomainName
+SLD of the domain name
.TP
.B tld
-string TLD of the DomainName
+TLD of the domain name
.TP
.B nameserver
-string Nameserver to retrieve
+Nameserver to retrieve
.UNINDENT
.sp
CLI Example:
@@ -178963,25 +187805,24 @@ salt \(aq*\(aq namecheap_domains_ns.get_info sld tld nameserver
.INDENT 0.0
.TP
.B salt.modules.namecheap_ns.update(sld, tld, nameserver, old_ip, new_ip)
-Deletes a nameserver
-.sp
-returns True if the nameserver was updated successfully
+Deletes a nameserver. Returns \fBTrue\fP if the nameserver was updated
+successfully.
.INDENT 7.0
.TP
.B sld
-string SLD of the DomainName
+SLD of the domain name
.TP
.B tld
-string TLD of the DomainName
+TLD of the domain name
.TP
.B nameserver
-string Nameserver to create
+Nameserver to create
.TP
.B old_ip
-string existing ip address
+Current ip address
.TP
.B new_ip
-string new ip address
+New ip address
.UNINDENT
.sp
CLI Example:
@@ -178998,46 +187839,19 @@ salt \(aq*\(aq namecheap_domains_ns.update sld tld nameserver old_ip new_ip
.UNINDENT
.SS salt.modules.namecheap_ssl module
.sp
-Namecheap management
+Namecheap SSL Certificate Management
.sp
New in version 2017.7.0.
-.SS General Notes
+.SS Prerequisites
.sp
-Use this module to manage ssl certificates through the namecheap
-api. The Namecheap settings will be set in grains.
-.SS Installation Prerequisites
-.INDENT 0.0
-.IP \(bu 2
-This module uses the following python libraries to communicate to
-the namecheap API:
-.INDENT 2.0
-.INDENT 3.5
-.INDENT 0.0
-.IP \(bu 2
-\fBrequests\fP
-.UNINDENT
-.INDENT 0.0
-.INDENT 3.5
+This module uses the \fBrequests\fP Python module to communicate to the namecheap
+API.
+.SS Configuration
.sp
-.nf
-.ft C
-pip install requests
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.UNINDENT
-.UNINDENT
-.IP \(bu 2
-As saltstack depends on \fBrequests\fP this shouldn\(aqt be a problem
-.UNINDENT
-.SS Prerequisite Configuration
+The Namecheap username, API key and URL should be set in the minion configuration
+file, or in the Pillar data.
.INDENT 0.0
-.IP \(bu 2
-The namecheap username, api key and url should be set in a minion
-configuration file or pillar
-.INDENT 2.0
.INDENT 3.5
.sp
.nf
@@ -179053,525 +187867,886 @@ namecheap.url: https://api.namecheap.com/xml.response
.fi
.UNINDENT
.UNINDENT
+.INDENT 0.0
+.TP
+.B salt.modules.namecheap_ssl.__virtual__()
+Check to make sure requests and xml are installed and requests
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.namecheap_ssl.activate(csr_file, certificate_id, web_server_type, approver_email=None, http_dc_validation=False, **kwargs)
-Activates a newly purchased SSL certificate
-.sp
-returns a dictionary of result values
+Activates a newly\-purchased SSL certificate. Returns a dictionary of result
+values.
.INDENT 7.0
.TP
-.B Required Parameters:
-.INDENT 7.0
-.TP
-.B csr
-string Certificate Signing Request
+.B csr_file
+Path to Certificate Signing Request file
.TP
.B certificate_id
-integer Unique ID of the SSL certificate you wish to activate
+Unique ID of the SSL certificate you wish to activate
.TP
.B web_server_type
+The type of certificate format to return. Possible values include:
.INDENT 7.0
-.TP
-.B string The type of certificate format to return
-.INDENT 7.0
-.TP
-.B Possible values: apacheopenssl, apachessl, apacheraven,
-apachessleay, c2net, ibmhttp, iplanet,
-domino, dominogo4625, dominogo4626,
-netscape, zeusv3, apache2,
-apacheapachessl, cobaltseries, cpanel,
-ensim, hsphere, ipswitch, plesk,
-tomcat, weblogic, website, webstar,
-iis, other, iis4, iis5
-.UNINDENT
+.IP \(bu 2
+apache2
+.IP \(bu 2
+apacheapachessl
+.IP \(bu 2
+apacheopenssl
+.IP \(bu 2
+apacheraven
+.IP \(bu 2
+apachessl
+.IP \(bu 2
+apachessleay
+.IP \(bu 2
+c2net
+.IP \(bu 2
+cobaltseries
+.IP \(bu 2
+cpanel
+.IP \(bu 2
+domino
+.IP \(bu 2
+dominogo4625
+.IP \(bu 2
+dominogo4626
+.IP \(bu 2
+ensim
+.IP \(bu 2
+hsphere
+.IP \(bu 2
+ibmhttp
+.IP \(bu 2
+iis
+.IP \(bu 2
+iis4
+.IP \(bu 2
+iis5
+.IP \(bu 2
+iplanet
+.IP \(bu 2
+ipswitch
+.IP \(bu 2
+netscape
+.IP \(bu 2
+other
+.IP \(bu 2
+plesk
+.IP \(bu 2
+tomcat
+.IP \(bu 2
+weblogic
+.IP \(bu 2
+website
+.IP \(bu 2
+webstar
+.IP \(bu 2
+zeusv3
.UNINDENT
.TP
.B approver_email
+The email ID which is on the approver email list.
+.sp
+\fBNOTE:\fP
.INDENT 7.0
-.TP
-.B string The email ID which is on the approver email list
-http_dc_validation must be set to False if this parameter
-is used
+.INDENT 3.5
+\fBhttp_dc_validation\fP must be set to \fBFalse\fP if this option is
+used.
+.UNINDENT
.UNINDENT
.TP
.B http_dc_validation
+False
+Whether or not to activate using HTTP\-based validation.
+.UNINDENT
+.sp
+\fBNOTE:\fP
.INDENT 7.0
-.TP
-.B bool An indicator that shows if certificate should be
-activated using HTTP\-based validation. Please specify
-True if you wish to use HTTP\-based validation.
-approver_email should be set to None if this parameter
-is used
+.INDENT 3.5
+For other parameters which may be required, see \fI\%here\fP\&.
.UNINDENT
.UNINDENT
-.TP
-.B Other required parameters:
-please see \fI\%https://www.namecheap.com/support/api/methods/ssl/activate.aspx\fP
-.UNINDENT
.sp
CLI Example:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+salt \(aqmy\-minion\(aq namecheap_ssl.activate my\-csr\-file my\-cert\-id apachessl
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.namecheap_ssl.create(years, certificate_type, promotion_code=None, sans_to_add=None)
+Creates a new SSL certificate. Returns the following information:
.INDENT 7.0
-.INDENT 3.5
-Creates a new SSL certificate
-.INDENT 0.0
-.TP
-.B returns a dictionary with the following values:
-issuccess Indicates whether SSL order was successful
-orderid A unique integer value that represents the order
-transactionid A unique integer value that represents the transaction
-chargedamount The amount charged for the order
-certificateid A unique integer value that represents the SSL
-created The date on which the certificate is created
-expires The date on which the certificate expires
-ssltype Type of SSL cerificate
-years Number of years for which the certificate is purchased
-status The current status of SSL certificate
-.TP
-.B Required parameters:
+.IP \(bu 2
+Whether or not the SSL order was successful
+.IP \(bu 2
+The certificate ID
+.IP \(bu 2
+The order ID
+.IP \(bu 2
+The transaction ID
+.IP \(bu 2
+The amount charged for the order
+.IP \(bu 2
+The date on which the certificate was created
+.IP \(bu 2
+The date on which the certificate will expire
+.IP \(bu 2
+The type of SSL certificate
+.IP \(bu 2
+The number of years for which the certificate was purchased
+.IP \(bu 2
+The current status of the SSL certificate
+.UNINDENT
.INDENT 7.0
.TP
.B years
-.INDENT 7.0
-.TP
-.B integer Number of years to register
-Default: 1
-.UNINDENT
+1
+Number of years to register
.TP
.B certificate_type
+Type of SSL Certificate. Possible values include:
.INDENT 7.0
-.TP
-.B string Type of SSL Certificate,
-.INDENT 7.0
-.TP
-.B Possible Values: QuickSSL Premium, RapidSSL, RapidSSL Wildcard,
-PremiumSSL, InstantSSL, PositiveSSL, PositiveSSL Wildcard,
-True BusinessID with EV, True BusinessID,
-True BusinessID Wildcard, True BusinessID Multi Domain,
-True BusinessID with EV Multi Domain, Secure Site,
-Secure Site Pro, Secure Site with EV,
-Secure Site Pro with EV, EssentialSSL, EssentialSSL Wildcard,
-InstantSSL Pro, PremiumSSL Wildcard, EV SSL, EV SSL SGC,
-SSL123, SSL Web Server, SGC Supercert, SSL Webserver EV,
-EV Multi Domain SSL, Multi Domain SSL,
-PositiveSSL Multi Domain, Unified Communications
+.IP \(bu 2
+EV Multi Domain SSL
+.IP \(bu 2
+EV SSL
+.IP \(bu 2
+EV SSL SGC
+.IP \(bu 2
+EssentialSSL
+.IP \(bu 2
+EssentialSSL Wildcard
+.IP \(bu 2
+InstantSSL
+.IP \(bu 2
+InstantSSL Pro
+.IP \(bu 2
+Multi Domain SSL
+.IP \(bu 2
+PositiveSSL
+.IP \(bu 2
+PositiveSSL Multi Domain
+.IP \(bu 2
+PositiveSSL Wildcard
+.IP \(bu 2
+PremiumSSL
+.IP \(bu 2
+PremiumSSL Wildcard
+.IP \(bu 2
+QuickSSL Premium
+.IP \(bu 2
+RapidSSL
+.IP \(bu 2
+RapidSSL Wildcard
+.IP \(bu 2
+SGC Supercert
+.IP \(bu 2
+SSL Web Server
+.IP \(bu 2
+SSL Webserver EV
+.IP \(bu 2
+SSL123
+.IP \(bu 2
+Secure Site
+.IP \(bu 2
+Secure Site Pro
+.IP \(bu 2
+Secure Site Pro with EV
+.IP \(bu 2
+Secure Site with EV
+.IP \(bu 2
+True BusinessID
+.IP \(bu 2
+True BusinessID Multi Domain
+.IP \(bu 2
+True BusinessID Wildcard
+.IP \(bu 2
+True BusinessID with EV
+.IP \(bu 2
+True BusinessID with EV Multi Domain
+.IP \(bu 2
+Unified Communications
.UNINDENT
-.UNINDENT
-.UNINDENT
-.TP
-.B Optional parameters:
-.INDENT 7.0
.TP
.B promotional_code
-string Promotional (coupon) code for the certificate
+An optional promo code to use when creating the certificate
.TP
.B sans_to_add
-.INDENT 7.0
-.TP
-.B integer This parameter defines the number of add\-on domains to be purchased in
+0
+This parameter defines the number of add\-on domains to be purchased in
addition to the default number of domains included with a multi\-domain
certificate. Each certificate that supports SANs has the default number
of domains included. You may check the default number of domains
-included and the maximum number of domains that can be added to it
-in the table below.
-Default: 0
+included and the maximum number of domains that can be added to it in
+the table below.
.UNINDENT
-.UNINDENT
-.UNINDENT
-.UNINDENT
-.UNINDENT
-.INDENT 7.0
-.TP
-.B Provider Product name Default number of Maximum number of Maximum number
-domains (domain from total domains of domains
-CSR is counted here) that can be
-.INDENT 7.0
-.INDENT 3.5
+.TS
+center;
+|l|l|l|l|l|.
+_
+T{
+Provider
+T} T{
+Product name
+T} T{
+Default number of
+domains (domain from
+CSR is counted here)
+T} T{
+Maximum number of
+total domains
+T} T{
+Maximum number
+of domains
+that can be
passed in
-SANStoADD
+sans_to_add
parameter
-.UNINDENT
-.UNINDENT
-.UNINDENT
-.INDENT 7.0
-.TP
-.B Comodo PositiveSSL 3 100 97
+T}
+_
+T{
+Comodo
+T} T{
+PositiveSSL
+Multi\-Domain
+T} T{
+3
+T} T{
+100
+T} T{
+97
+T}
+_
+T{
+Comodo
+T} T{
Multi\-Domain
-.UNINDENT
-.INDENT 7.0
-.TP
-.B Comodo Multi\-Domain 3 100 97
SSL
-.UNINDENT
-.INDENT 7.0
-.TP
-.B Comodo EV Multi\- 3 100 97
+T} T{
+3
+T} T{
+100
+T} T{
+97
+T}
+_
+T{
+Comodo
+T} T{
+EV Multi\-
Domain SSL
-.UNINDENT
-.INDENT 7.0
-.TP
-.B Comodo Unified 3 100 97
+T} T{
+3
+T} T{
+100
+T} T{
+97
+T}
+_
+T{
+Comodo
+T} T{
+Unified
Communications
-.UNINDENT
-.INDENT 7.0
-.TP
-.B GeoTrust QuickSSL 1 1 domain + The only
-.INDENT 7.0
-.TP
-.B Premium 4 subdomains supported
+T} T{
+3
+T} T{
+100
+T} T{
+97
+T}
+_
+T{
+GeoTrust
+T} T{
+QuickSSL
+Premium
+T} T{
+1
+T} T{
+1 domain +
+4 subdomains
+T} T{
+The only
+supported
value is 4
-.UNINDENT
-.UNINDENT
-.INDENT 7.0
-.TP
-.B GeoTrust True 5 25 20
+T}
+_
+T{
+GeoTrust
+T} T{
+True
BusinessID
with EV
Multi\-Domain
-.UNINDENT
-.INDENT 7.0
-.TP
-.B GeoTrust True Business 5 25 20
+T} T{
+5
+T} T{
+25
+T} T{
+20
+T}
+_
+T{
+GeoTrust
+T} T{
+True Business
ID Multi\-
Domain
-.UNINDENT
-.INDENT 7.0
-.TP
-.B Thawte SSL Web 1 25 24
+T} T{
+5
+T} T{
+25
+T} T{
+20
+T}
+_
+T{
+Thawte
+T} T{
+SSL Web
Server
-.UNINDENT
-.INDENT 7.0
-.TP
-.B Thawte SSL Web 1 25 24
+T} T{
+1
+T} T{
+25
+T} T{
+24
+T}
+_
+T{
+Thawte
+T} T{
+SSL Web
Server with
EV
-.UNINDENT
-.INDENT 7.0
-.TP
-.B Symantec Secure Site 1 25 24
+T} T{
+1
+T} T{
+25
+T} T{
+24
+T}
+_
+T{
+Thawte
+T} T{
+SGC Supercerts
+T} T{
+1
+T} T{
+25
+T} T{
+24
+T}
+_
+T{
+Symantec
+T} T{
+Secure Site
Pro with EV
-.UNINDENT
-.INDENT 7.0
-.TP
-.B Symantec Secure Site 1 25 24
+T} T{
+1
+T} T{
+25
+T} T{
+24
+T}
+_
+T{
+Symantec
+T} T{
+Secure Site
with EV
-.UNINDENT
-.INDENT 7.0
-.TP
-.B Symantec Secure Site 1 25 24
+T} T{
+1
+T} T{
+25
+T} T{
+24
+T}
+_
+T{
+Symantec
+T} T{
+Secure Site
+T} T{
+1
+T} T{
+25
+T} T{
+24
+T}
+_
+T{
+Symantec
+T} T{
+Secure Site
Pro
-.UNINDENT
+T} T{
+1
+T} T{
+25
+T} T{
+24
+T}
+_
+.TE
+.sp
+CLI Example:
.INDENT 7.0
.INDENT 3.5
-CLI Example:
+.sp
+.nf
+.ft C
+salt \(aqmy\-minion\(aq namecheap_ssl.create 2 RapidSSL
+.ft P
+.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.namecheap_ssl.get_info(certificate_id, returncertificate=False, returntype=None)
-Retrieves information about the requested SSL certificate
+Retrieves information about the requested SSL certificate. Returns a
+dictionary of information about the SSL certificate with two keys:
.INDENT 7.0
-.TP
-.B returns a dictionary of information about the SSL certificate with two keys
-"ssl" contains the metadata information
-"certificate" contains the details for the certificate like
+.IP \(bu 2
+\fBssl\fP \- Contains the metadata information
+.IP \(bu 2
+\fBcertificate\fP \- Contains the details for the certificate such as the
+CSR, Approver, and certificate data
+.UNINDENT
.INDENT 7.0
-.INDENT 3.5
-the CSR, Approver, and certificate data
-.UNINDENT
-.UNINDENT
.TP
.B certificate_id
-integer Unique ID of the SSL certificate
+Unique ID of the SSL certificate
.TP
.B returncertificate
-bool True to ask for the certificate in response
+False
+Set to \fBTrue\fP to ask for the certificate in response
.TP
.B returntype
-.INDENT 7.0
-.TP
-.B string Type of returned certificate. Parameter takes "Individual (for X.509 format) or PKCS7"
-Required if returncertificate is True
-.UNINDENT
-.UNINDENT
+Optional type for the returned certificate. Can be either "Individual"
+(for X.509 format) or "PKCS7"
.sp
-CLI Example:
-.UNINDENT
-.INDENT 0.0
-.TP
-.B salt.modules.namecheap_ssl.get_list(**kwargs)
-Returns a list of SSL certificates for a particular user
-.sp
-Optional parameters:
+\fBNOTE:\fP
.INDENT 7.0
.INDENT 3.5
-.INDENT 0.0
-.TP
-.B ListType
-.INDENT 7.0
-.TP
-.B string Possible values: All,Processing,EmailSent,
-.INDENT 7.0
-.INDENT 3.5
-TechnicalProblem,InProgress,Completed,
-Deactivated,Active,Cancelled,NewPurchase,
-NewRenewal
-.UNINDENT
-.UNINDENT
-.sp
-Default: All
-.UNINDENT
-.TP
-.B SearchTerm
-string Keyword to look for on the SSL list
-.TP
-.B Page
-.INDENT 7.0
-.TP
-.B integer Page to return
-Default: 1
-.UNINDENT
-.TP
-.B PageSize
-.INDENT 7.0
-.TP
-.B integer Total number of SSL certificates to display in a page
-Minimum value is 10 and maximum value is 100
-Default: 20
-.UNINDENT
-.TP
-.B SoryBy
-.INDENT 7.0
-.TP
-.B string Possible values are PURCHASEDATE,PURCHASEDATE_DESC,
-SSLTYPE,SSLTYPE_DESC,
-EXPIREDATETIME,EXPIREDATETIME_DESC,
-Host_Name,Host_Name_DESC
-.UNINDENT
+Required if \fBreturncertificate\fP is \fBTrue\fP
.UNINDENT
.UNINDENT
.UNINDENT
.sp
CLI Example:
-.UNINDENT
-.INDENT 0.0
-.TP
-.B salt.modules.namecheap_ssl.parse_csr(csr_file, certificate_type, http_dc_validation=False)
-Parses the CSR
-.sp
-returns a dictionary of result values
-.sp
-Required parameters:
.INDENT 7.0
.INDENT 3.5
-.INDENT 0.0
-.TP
-.B csr_file
-string Certificate Signing Request File
-.TP
-.B certificate_type
-.INDENT 7.0
-.TP
-.B string Type of SSL Certificate,
-.INDENT 7.0
-.TP
-.B Possible Values: QuickSSL Premium, RapidSSL, RapidSSL Wildcard,
-PremiumSSL, InstantSSL, PositiveSSL, PositiveSSL Wildcard,
-True BusinessID with EV, True BusinessID,
-True BusinessID Wildcard, True BusinessID Multi Domain,
-True BusinessID with EV Multi Domain, Secure Site,
-Secure Site Pro, Secure Site with EV,
-Secure Site Pro with EV, EssentialSSL, EssentialSSL Wildcard,
-InstantSSL Pro, PremiumSSL Wildcard, EV SSL, EV SSL SGC,
-SSL123, SSL Web Server, SGC Supercert, SSL Webserver EV,
-EV Multi Domain SSL, Multi Domain SSL,
-PositiveSSL Multi Domain, Unified Communications
-.UNINDENT
-.UNINDENT
-.UNINDENT
-.UNINDENT
-.UNINDENT
-.sp
-Optional parameter:
-.INDENT 7.0
-.INDENT 3.5
-.INDENT 0.0
-.TP
-.B http_dc_validation
-.INDENT 7.0
-.TP
-.B bool True if a Comodo certificate and validation should be done with files
-instead of emails and to return the info to do so
-.UNINDENT
-.UNINDENT
-.UNINDENT
-.UNINDENT
-.sp
-CLI Example:
-.UNINDENT
-.INDENT 0.0
-.TP
-.B salt.modules.namecheap_ssl.reissue(csr_file, certificate_id, web_server_type, approver_email=None, http_dc_validation=False, **kwargs)
-Reissues a purchased SSL certificate
-.sp
-returns a dictionary of result values
-.INDENT 7.0
-.TP
-.B Required Parameters:
-.INDENT 7.0
-.TP
-.B csr
-string Certificate Signing Request
-.TP
-.B certificate_id
-integer Unique ID of the SSL certificate you wish to activate
-.TP
-.B web_server_type
-.INDENT 7.0
-.TP
-.B string The type of certificate format to return
-.INDENT 7.0
-.TP
-.B Possible values: apacheopenssl, apachessl, apacheraven,
-apachessleay, c2net, ibmhttp, iplanet,
-domino, dominogo4625, dominogo4626,
-netscape, zeusv3, apache2,
-apacheapachessl, cobaltseries, cpanel,
-ensim, hsphere, ipswitch, plesk,
-tomcat, weblogic, website, webstar,
-iis, other, iis4, iis5
-.UNINDENT
-.UNINDENT
-.TP
-.B approver_email
-.INDENT 7.0
-.TP
-.B string The email ID which is on the approver email list
-http_dc_validation must be set to False if this parameter
-is used
-.UNINDENT
-.TP
-.B http_dc_validation
-.INDENT 7.0
-.TP
-.B bool An indicator that shows if certificate should be
-activated using HTTP\-based validation. Please specify
-True if you wish to use HTTP\-based validation.
-approver_email should be set to None if this parameter
-is used
-.UNINDENT
-.UNINDENT
-.TP
-.B Other required parameters:
-please see \fI\%https://www.namecheap.com/support/api/methods/ssl/reissue.aspx\fP
-.UNINDENT
-.sp
-CLI Example:
-.UNINDENT
-.INDENT 0.0
-.TP
-.B salt.modules.namecheap_ssl.renew(years, certificate_id, certificate_type, promotion_code=None)
-Renews an SSL certificate if it is ACTIVE and Expires <= 30 days
-.INDENT 7.0
-.TP
-.B returns a dictionary with the following values:
-orderid A unique integer value that represents the order
-transactionid A unique integer value that represents the transaction
-chargedamount The amount charged for the order
-certificateid A unique integer value that represents the SSL
-.TP
-.B Required parameters:
-.INDENT 7.0
-.TP
-.B years
-.INDENT 7.0
-.TP
-.B integer Number of years to register
-Default: 1
-.UNINDENT
-.TP
-.B certificate_id
-integer Unique identifier for the existing certificate to renew
-.TP
-.B certificate_type
-.INDENT 7.0
-.TP
-.B string Type of SSL Certificate,
-.INDENT 7.0
-.TP
-.B Possible Values: QuickSSL Premium, RapidSSL, RapidSSL Wildcard,
-PremiumSSL, InstantSSL, PositiveSSL, PositiveSSL Wildcard,
-True BusinessID with EV, True BusinessID,
-True BusinessID Wildcard, True BusinessID Multi Domain,
-True BusinessID with EV Multi Domain, Secure Site,
-Secure Site Pro, Secure Site with EV,
-Secure Site Pro with EV, EssentialSSL, EssentialSSL Wildcard,
-InstantSSL Pro, PremiumSSL Wildcard, EV SSL, EV SSL SGC,
-SSL123, SSL Web Server, SGC Supercert, SSL Webserver EV,
-EV Multi Domain SSL, Multi Domain SSL,
-PositiveSSL Multi Domain, Unified Communications
-.UNINDENT
-.UNINDENT
-.UNINDENT
-.TP
-.B Optional parameters:
-.INDENT 7.0
-.TP
-.B promotional_code
-string Promotional (coupon) code for the certificate
-.UNINDENT
-.UNINDENT
-.sp
-CLI Example:
-.UNINDENT
-.SS salt.modules.namecheap_users module
-.sp
-Namecheap management
-.sp
-New in version 2017.7.0.
-
-.SS General Notes
-.sp
-Use this module to manage users through the namecheap
-api. The Namecheap settings will be set in grains.
-.SS Installation Prerequisites
-.INDENT 0.0
-.IP \(bu 2
-This module uses the following python libraries to communicate to
-the namecheap API:
-.INDENT 2.0
-.INDENT 3.5
-.INDENT 0.0
-.IP \(bu 2
-\fBrequests\fP
-.UNINDENT
-.INDENT 0.0
-.INDENT 3.5
.sp
.nf
.ft C
-pip install requests
+salt \(aqmy\-minion\(aq namecheap_ssl.get_info my\-cert\-id
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
-.UNINDENT
-.IP \(bu 2
-As saltstack depends on \fBrequests\fP this shouldn\(aqt be a problem
-.UNINDENT
-.SS Prerequisite Configuration
.INDENT 0.0
+.TP
+.B salt.modules.namecheap_ssl.get_list(**kwargs)
+Returns a list of SSL certificates for a particular user
+.INDENT 7.0
+.TP
+.B ListType
+All
+Possible values:
+.INDENT 7.0
.IP \(bu 2
-The namecheap username, api key and url should be set in a minion
-configuration file or pillar
-.INDENT 2.0
+All
+.IP \(bu 2
+Processing
+.IP \(bu 2
+EmailSent
+.IP \(bu 2
+TechnicalProblem
+.IP \(bu 2
+InProgress
+.IP \(bu 2
+Completed
+.IP \(bu 2
+Deactivated
+.IP \(bu 2
+Active
+.IP \(bu 2
+Cancelled
+.IP \(bu 2
+NewPurchase
+.IP \(bu 2
+NewRenewal
+.UNINDENT
+.INDENT 7.0
+.TP
+.B SearchTerm
+Keyword to look for on the SSL list
+.TP
+.B Page
+1
+Page number to return
+.TP
+.B PageSize
+20
+Total number of SSL certificates to display per page (minimum:
+\fB10\fP, maximum: \fB100\fP)
+.TP
+.B SoryBy
+One of \fBPURCHASEDATE\fP, \fBPURCHASEDATE_DESC\fP, \fBSSLTYPE\fP,
+\fBSSLTYPE_DESC\fP, \fBEXPIREDATETIME\fP, \fBEXPIREDATETIME_DESC\fP,
+\fBHost_Name\fP, or \fBHost_Name_DESC\fP
+.UNINDENT
+.UNINDENT
+.sp
+CLI Example:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+salt \(aqmy\-minion\(aq namecheap_ssl.get_list Processing
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.UNINDENT
+.INDENT 0.0
+.TP
+.B salt.modules.namecheap_ssl.parse_csr(csr_file, certificate_type, http_dc_validation=False)
+Parses the CSR. Returns a dictionary of result values.
+.INDENT 7.0
+.TP
+.B csr_file
+Path to Certificate Signing Request file
+.TP
+.B certificate_type
+Type of SSL Certificate. Possible values include:
+.INDENT 7.0
+.IP \(bu 2
+EV Multi Domain SSL
+.IP \(bu 2
+EV SSL
+.IP \(bu 2
+EV SSL SGC
+.IP \(bu 2
+EssentialSSL
+.IP \(bu 2
+EssentialSSL Wildcard
+.IP \(bu 2
+InstantSSL
+.IP \(bu 2
+InstantSSL Pro
+.IP \(bu 2
+Multi Domain SSL
+.IP \(bu 2
+PositiveSSL
+.IP \(bu 2
+PositiveSSL Multi Domain
+.IP \(bu 2
+PositiveSSL Wildcard
+.IP \(bu 2
+PremiumSSL
+.IP \(bu 2
+PremiumSSL Wildcard
+.IP \(bu 2
+QuickSSL Premium
+.IP \(bu 2
+RapidSSL
+.IP \(bu 2
+RapidSSL Wildcard
+.IP \(bu 2
+SGC Supercert
+.IP \(bu 2
+SSL Web Server
+.IP \(bu 2
+SSL Webserver EV
+.IP \(bu 2
+SSL123
+.IP \(bu 2
+Secure Site
+.IP \(bu 2
+Secure Site Pro
+.IP \(bu 2
+Secure Site Pro with EV
+.IP \(bu 2
+Secure Site with EV
+.IP \(bu 2
+True BusinessID
+.IP \(bu 2
+True BusinessID Multi Domain
+.IP \(bu 2
+True BusinessID Wildcard
+.IP \(bu 2
+True BusinessID with EV
+.IP \(bu 2
+True BusinessID with EV Multi Domain
+.IP \(bu 2
+Unified Communications
+.UNINDENT
+.TP
+.B http_dc_validation
+False
+Set to \fBTrue\fP if a Comodo certificate and validation should be
+done with files instead of emails and to return the info to do so
+.UNINDENT
+.sp
+CLI Example:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+salt \(aqmy\-minion\(aq namecheap_ssl.parse_csr my\-csr\-file PremiumSSL
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.UNINDENT
+.INDENT 0.0
+.TP
+.B salt.modules.namecheap_ssl.reissue(csr_file, certificate_id, web_server_type, approver_email=None, http_dc_validation=False, **kwargs)
+Reissues a purchased SSL certificate. Returns a dictionary of result
+values.
+.INDENT 7.0
+.TP
+.B csr_file
+Path to Certificate Signing Request file
+.TP
+.B certificate_id
+Unique ID of the SSL certificate you wish to activate
+.TP
+.B web_server_type
+The type of certificate format to return. Possible values include:
+.INDENT 7.0
+.IP \(bu 2
+apache2
+.IP \(bu 2
+apacheapachessl
+.IP \(bu 2
+apacheopenssl
+.IP \(bu 2
+apacheraven
+.IP \(bu 2
+apachessl
+.IP \(bu 2
+apachessleay
+.IP \(bu 2
+c2net
+.IP \(bu 2
+cobaltseries
+.IP \(bu 2
+cpanel
+.IP \(bu 2
+domino
+.IP \(bu 2
+dominogo4625
+.IP \(bu 2
+dominogo4626
+.IP \(bu 2
+ensim
+.IP \(bu 2
+hsphere
+.IP \(bu 2
+ibmhttp
+.IP \(bu 2
+iis
+.IP \(bu 2
+iis4
+.IP \(bu 2
+iis5
+.IP \(bu 2
+iplanet
+.IP \(bu 2
+ipswitch
+.IP \(bu 2
+netscape
+.IP \(bu 2
+other
+.IP \(bu 2
+plesk
+.IP \(bu 2
+tomcat
+.IP \(bu 2
+weblogic
+.IP \(bu 2
+website
+.IP \(bu 2
+webstar
+.IP \(bu 2
+zeusv3
+.UNINDENT
+.TP
+.B approver_email
+The email ID which is on the approver email list.
+.sp
+\fBNOTE:\fP
+.INDENT 7.0
+.INDENT 3.5
+\fBhttp_dc_validation\fP must be set to \fBFalse\fP if this option is
+used.
+.UNINDENT
+.UNINDENT
+.TP
+.B http_dc_validation
+False
+Whether or not to activate using HTTP\-based validation.
+.UNINDENT
+.sp
+\fBNOTE:\fP
+.INDENT 7.0
+.INDENT 3.5
+For other parameters which may be required, see \fI\%here\fP\&.
+.UNINDENT
+.UNINDENT
+.sp
+CLI Example:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+salt \(aqmy\-minion\(aq namecheap_ssl.reissue my\-csr\-file my\-cert\-id apachessl
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.UNINDENT
+.INDENT 0.0
+.TP
+.B salt.modules.namecheap_ssl.renew(years, certificate_id, certificate_type, promotion_code=None)
+Renews an SSL certificate if it is ACTIVE and Expires <= 30 days. Returns
+the following information:
+.INDENT 7.0
+.IP \(bu 2
+The certificate ID
+.IP \(bu 2
+The order ID
+.IP \(bu 2
+The transaction ID
+.IP \(bu 2
+The amount charged for the order
+.UNINDENT
+.INDENT 7.0
+.TP
+.B years
+1
+Number of years to register
+.TP
+.B certificate_id
+Unique ID of the SSL certificate you wish to renew
+.TP
+.B certificate_type
+Type of SSL Certificate. Possible values include:
+.INDENT 7.0
+.IP \(bu 2
+EV Multi Domain SSL
+.IP \(bu 2
+EV SSL
+.IP \(bu 2
+EV SSL SGC
+.IP \(bu 2
+EssentialSSL
+.IP \(bu 2
+EssentialSSL Wildcard
+.IP \(bu 2
+InstantSSL
+.IP \(bu 2
+InstantSSL Pro
+.IP \(bu 2
+Multi Domain SSL
+.IP \(bu 2
+PositiveSSL
+.IP \(bu 2
+PositiveSSL Multi Domain
+.IP \(bu 2
+PositiveSSL Wildcard
+.IP \(bu 2
+PremiumSSL
+.IP \(bu 2
+PremiumSSL Wildcard
+.IP \(bu 2
+QuickSSL Premium
+.IP \(bu 2
+RapidSSL
+.IP \(bu 2
+RapidSSL Wildcard
+.IP \(bu 2
+SGC Supercert
+.IP \(bu 2
+SSL Web Server
+.IP \(bu 2
+SSL Webserver EV
+.IP \(bu 2
+SSL123
+.IP \(bu 2
+Secure Site
+.IP \(bu 2
+Secure Site Pro
+.IP \(bu 2
+Secure Site Pro with EV
+.IP \(bu 2
+Secure Site with EV
+.IP \(bu 2
+True BusinessID
+.IP \(bu 2
+True BusinessID Multi Domain
+.IP \(bu 2
+True BusinessID Wildcard
+.IP \(bu 2
+True BusinessID with EV
+.IP \(bu 2
+True BusinessID with EV Multi Domain
+.IP \(bu 2
+Unified Communications
+.UNINDENT
+.TP
+.B promotional_code
+An optional promo code to use when renewing the certificate
+.UNINDENT
+.sp
+CLI Example:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+salt \(aqmy\-minion\(aq namecheap_ssl.renew 1 my\-cert\-id RapidSSL
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.UNINDENT
+.SS salt.modules.namecheap_users module
+.sp
+Namecheap User Management
+.sp
+New in version 2017.7.0.
+
+.SS Prerequisites
+.sp
+This module uses the \fBrequests\fP Python module to communicate to the namecheap
+API.
+.SS Configuration
+.sp
+The Namecheap username, API key and URL should be set in the minion configuration
+file, or in the Pillar data.
+.INDENT 0.0
.INDENT 3.5
.sp
.nf
@@ -179587,18 +188762,23 @@ namecheap.url: https://api.namecheap.com/xml.response
.fi
.UNINDENT
.UNINDENT
+.INDENT 0.0
+.TP
+.B salt.modules.namecheap_users.__virtual__()
+Check to make sure requests and xml are installed and requests
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.namecheap_users.check_balances(minimum=100)
Checks if the provided minimum value is present in the user\(aqs account.
.sp
-Returns a boolean. Returns \fBFalse\fP if the user\(aqs account balance is less than the
-provided minimum or \fBTrue\fP if greater than the minimum.
+Returns a boolean. Returns \fBFalse\fP if the user\(aqs account balance is less
+than the provided minimum or \fBTrue\fP if greater than the minimum.
.INDENT 7.0
.TP
.B minimum
-The value to check. Defaults to \fB100\fP\&.
+100
+The value to check
.UNINDENT
.sp
CLI Example:
@@ -179617,13 +188797,18 @@ salt \(aqmy\-minion\(aq namecheap_users.check_balances minimum=150
.INDENT 0.0
.TP
.B salt.modules.namecheap_users.get_balances()
-Gets information about fund in the user\(aqs account. This method returns the following information:
-Available Balance, Account Balance, Earned Amount, Withdrawable Amount and Funds Required for AutoRenew.
+Gets information about fund in the user\(aqs account. This method returns the
+following information: Available Balance, Account Balance, Earned Amount,
+Withdrawable Amount and Funds Required for AutoRenew.
.sp
-NOTE: If a domain setup with automatic renewal is expiring within the next 90 days,
-the FundsRequiredForAutoRenew attribute shows the amount needed in your Namecheap account to complete auto renewal.
-.sp
-returns a dictionary of the results
+\fBNOTE:\fP
+.INDENT 7.0
+.INDENT 3.5
+If a domain setup with automatic renewal is expiring within the next 90
+days, the FundsRequiredForAutoRenew attribute shows the amount needed
+in your Namecheap account to complete auto renewal.
+.UNINDENT
+.UNINDENT
.sp
CLI Example:
.INDENT 7.0
@@ -179644,6 +188829,11 @@ Helpers for the NAPALM modules.
.sp
New in version 2017.7.0.
+.INDENT 0.0
+.TP
+.B salt.modules.napalm.__virtual__()
+NAPALM library must be installed for this module to work and run in a (proxy) minion.
+.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.napalm.alive(*args, **kwargs)
@@ -179852,6 +189042,11 @@ it requires \fI\%NAPALM\fP library to be installed: \fBpip install napalm\fP\&.
Please check \fI\%Installation\fP for complete details.
.INDENT 0.0
.TP
+.B salt.modules.napalm_acl.__virtual__()
+This module requires both NAPALM and Capirca.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.napalm_acl.get_filter_pillar(filter_name, pillar_key=\(aqacl\(aq, pillarenv=None, saltenv=None)
Helper that can be used inside a state SLS,
in order to get the filter configuration given its name.
@@ -180076,11 +189271,14 @@ netacl:
\- my\-filter:
terms:
\- my\-term:
- source_port: [1234, 1235]
+ source_port:
+ \- 1234
+ \- 1235
action: reject
\- my\-other\-term:
source_port:
- \- [5678, 5680]
+ \- \- 5678
+ \- 5680
protocol: tcp
action: accept
.ft P
@@ -180241,7 +189439,9 @@ acl:
\- my\-filter:
terms:
\- my\-term:
- source_port: [1234, 1235]
+ source_port:
+ \- 1234
+ \- 1235
protocol:
\- tcp
\- udp
@@ -180353,18 +189553,10 @@ A special service to choose from. This is a helper so the user is able to
select a source just using the name, instead of specifying a destination_port and protocol.
Allows the same options as \fBsource_service\fP\&.
.TP
-.B
-.nf
-**
-.fi
-term_fields
-Term attributes.
-To see what fields are supported, please consult the list of supported \fI\%keywords\fP\&.
-Some platforms have few other \fI\%optional\fP keywords.
-.INDENT 7.0
-.INDENT 3.5
-.UNINDENT
-.UNINDENT
+.B term_fields
+Term attributes. To see what fields are supported, please consult the
+list of supported \fI\%keywords\fP\&. Some platforms have a few other \fI\%optional\fP
+keywords.
.UNINDENT
.sp
\fBNOTE:\fP
@@ -180618,8 +189810,10 @@ a single value, either a list of values, but also they can select port ranges. E
.nf
.ft C
source_port:
- \- [1000, 2000]
- \- [3000, 4000]
+ \- \- 1000
+ \- 2000
+ \- \- 3000
+ \- 4000
.ft P
.fi
.UNINDENT
@@ -180734,6 +189928,11 @@ unix
.sp
New in version 2016.11.0.
+.INDENT 0.0
+.TP
+.B salt.modules.napalm_bgp.__virtual__()
+NAPALM library must be installed for this module to work and run in a (proxy) minion.
+.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.napalm_bgp.config(*args, **kwargs)
@@ -180746,13 +189945,15 @@ Provides the BGP configuration on the device.
\fBgroup\fP \-\- Name of the group selected to display the configuration.
.IP \(bu 2
\fBneighbor\fP \-\- IP Address of the neighbor to display the configuration.
+If the group parameter is not specified, the neighbor setting will be
+ignored.
.UNINDENT
+.TP
+.B Returns
+A dictionary containing the BGP configuration from the network
+device. The keys of the main dictionary are the group names.
.UNINDENT
.sp
-If the group parameter is not specified, the neighbor setting will be ignored.
-:return: A dictionary containing the BGP configuration from the network device.
-The keys of the main dictionary are the group names.
-.sp
Each group has the following properties:
.INDENT 7.0
.INDENT 3.5
@@ -180896,15 +190097,11 @@ Provides details regarding the BGP sessions configured on the network device.
\fBneighbor\fP \-\- IP Address of a specific neighbor.
.TP
.B Returns
-A dictionary with the statistics of the all/selected BGP neighbors.
-.UNINDENT
-.sp
-Outer dictionary keys represent the VRF name.
-Keys of inner dictionary represent the AS numbers, while the values are lists of dictionaries,
-having the following keys:
+A dictionary with the statistics of the all/selected BGP
+neighbors. Outer dictionary keys represent the VRF name. Keys of inner
+dictionary represent the AS numbers, while the values are lists of
+dictionaries, having the following keys:
.INDENT 7.0
-.INDENT 3.5
-.INDENT 0.0
.IP \(bu 2
up (True/False)
.IP \(bu 2
@@ -180974,7 +190171,7 @@ advertised_prefix_count (int)
.IP \(bu 2
flap_count (int)
.UNINDENT
-.UNINDENT
+
.UNINDENT
.sp
CLI Example:
@@ -181070,6 +190267,11 @@ New in version 2016.11.0.
.sp
Changed in version 2017.7.0.
+.INDENT 0.0
+.TP
+.B salt.modules.napalm_network.__virtual__()
+NAPALM library must be installed for this module to work and run in a (proxy) minion.
+.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.napalm_network.arp(*args, **kwargs)
@@ -181221,9 +190423,8 @@ salt \(aq*\(aq net.compare_config
New in version 2017.7.0.
.sp
-Return the whole configuration of the network device.
-By default, it will return all possible configuration
-sources supported by the network device.
+Return the whole configuration of the network device. By default, it will
+return all possible configuration sources supported by the network device.
At most, there will be:
.INDENT 7.0
.IP \(bu 2
@@ -181234,11 +190435,11 @@ startup config
candidate config
.UNINDENT
.sp
-To return only one of the configurations, you can use
-the \fBsource\fP argument.
+To return only one of the configurations, you can use the \fBsource\fP
+argument.
.INDENT 7.0
.TP
-.B source (optional)
+.B source
Which configuration type you want to display, default is all of them.
.sp
Options:
@@ -181516,7 +190717,8 @@ Returns details of the interfaces on the device.
.INDENT 7.0
.TP
.B Returns
-Returns a dictionary of dictionaries. The keys for the first dictionary will be the interfaces in the devices.
+Returns a dictionary of dictionaries. The keys for the first
+dictionary will be the interfaces in the devices.
.UNINDENT
.sp
CLI Example:
@@ -181567,7 +190769,12 @@ Returns IP addresses configured on the device.
.INDENT 7.0
.TP
.B Returns
-A dictionary with the IPv4 and IPv6 addresses of the interfaces. Returns all configured IP addresses on all interfaces as a dictionary of dictionaries. Keys of the main dictionary represent the name of the interface. Values of the main dictionary represent are dictionaries that may consist of two keys \(aqipv4\(aq and \(aqipv6\(aq (one, both or none) which are themselvs dictionaries with the IP addresses as keys.
+A dictionary with the IPv4 and IPv6 addresses of the interfaces.
+Returns all configured IP addresses on all interfaces as a dictionary
+of dictionaries. Keys of the main dictionary represent the name of the
+interface. Values of the main dictionary represent are dictionaries
+that may consist of two keys \(aqipv4\(aq and \(aqipv6\(aq (one, both or none)
+which are themselvs dictionaries with the IP addresses as keys.
.UNINDENT
.sp
CLI Example:
@@ -181630,7 +190837,8 @@ Returns a detailed view of the LLDP neighbors.
\fBinterface\fP \-\- interface name to filter on
.TP
.B Returns
-A dictionary with the LLDL neighbors. The keys are the interfaces with LLDP activated on.
+A dictionary with the LLDL neighbors. The keys are the
+interfaces with LLDP activated on.
.UNINDENT
.sp
CLI Example:
@@ -181774,6 +190982,21 @@ salt \(aq*\(aq net.load_config filename=\(aq/absolute/path/to/your/file\(aq comm
.UNINDENT
.sp
Example output:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+{
+ \(aqcomment\(aq: \(aqConfiguration discarded.\(aq,
+ \(aqalready_configured\(aq: False,
+ \(aqresult\(aq: True,
+ \(aqdiff\(aq: \(aq[edit interfaces xe\-0/0/5]+ description "Adding a description";\(aq
+}
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
@@ -181953,19 +191176,14 @@ Default variables/context passed to the template.
New in version 2016.11.2.
.TP
-.B
-.nf
-**
-.fi
-template_vars
+.B template_vars
Dictionary with the arguments/context to be used when the template is rendered.
.sp
\fBNOTE:\fP
.INDENT 7.0
.INDENT 3.5
-Do not explicitly specify this argument.
-This represents any other variable that will be sent
-to the template rendering system.
+Do not explicitly specify this argument. This represents any other
+variable that will be sent to the template rendering system.
Please see the examples below!
.UNINDENT
.UNINDENT
@@ -181977,13 +191195,17 @@ a dictionary having the following keys:
.UNINDENT
.INDENT 7.0
.IP \(bu 2
-result (bool): if the config was applied successfully. It is \fBFalse\fP only in case of failure. In case there are no changes to be applied and successfully performs all operations it is still \fBTrue\fP and so will be the \fBalready_configured\fP flag (example below)
+result (bool): if the config was applied successfully. It is \fBFalse\fP
+only in case of failure. In case there are no changes to be applied and
+successfully performs all operations it is still \fBTrue\fP and so will be
+the \fBalready_configured\fP flag (example below)
.IP \(bu 2
comment (str): a message for the user
.IP \(bu 2
already_configured (bool): flag to check if there were no changes applied
.IP \(bu 2
-loaded_config (str): the configuration loaded on the device, after rendering the template. Requires \fBdebug\fP to be set as \fBTrue\fP
+loaded_config (str): the configuration loaded on the device, after
+rendering the template. Requires \fBdebug\fP to be set as \fBTrue\fP
.IP \(bu 2
diff (str): returns the config changes applied
.UNINDENT
@@ -182375,6 +191597,11 @@ unix
.sp
New in version 2016.11.0.
+.INDENT 0.0
+.TP
+.B salt.modules.napalm_ntp.__virtual__()
+NAPALM library must be installed for this module to work and run in a (proxy) minion.
+.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.napalm_ntp.delete_peers(*args, **kwargs)
@@ -182386,17 +191613,18 @@ Removes NTP peers configured on the device.
.IP \(bu 2
\fBpeers\fP \-\- list of IP Addresses/Domain Names to be removed as NTP peers
.IP \(bu 2
-\fB(bool)\fP (\fItest\fP) \-\- discard loaded config. By default \fItest\fP is False (will not dicard the changes)
+\fB(bool)\fP (\fIcommit\fP) \-\- discard loaded config. By default \fItest\fP is False (will
+not dicard the changes)
+.IP \(bu 2
+\fB(bool)\fP \-\- commit loaded config. By default \fIcommit\fP is True
+(will commit the changes). Useful when the user does not want to commit
+after each change, but after a couple.
.UNINDENT
-.TP
-.B Commit commit (bool)
-commit loaded config. By default \fIcommit\fP is True (will commit the changes). Useful when
.UNINDENT
.sp
-the user does not want to commit after each change, but after a couple.
-.sp
-By default this function will commit the config changes (if any). To load without committing, use the \fIcommit\fP
-option. For dry run use the \fItest\fP argument.
+By default this function will commit the config changes (if any). To load
+without committing, use the \fBcommit\fP option. For a dry run, use the
+\fBtest\fP argument.
.sp
CLI Example:
.INDENT 7.0
@@ -182421,19 +191649,21 @@ Removes NTP servers configured on the device.
.B Parameters
.INDENT 7.0
.IP \(bu 2
-\fBservers\fP \-\- list of IP Addresses/Domain Names to be removed as NTP servers
+\fBservers\fP \-\- list of IP Addresses/Domain Names to be removed as NTP
+servers
.IP \(bu 2
-\fB(bool)\fP (\fItest\fP) \-\- discard loaded config. By default \fItest\fP is False (will not dicard the changes)
+\fB(bool)\fP (\fIcommit\fP) \-\- discard loaded config. By default \fItest\fP is False (will
+not dicard the changes)
+.IP \(bu 2
+\fB(bool)\fP \-\- commit loaded config. By default \fIcommit\fP is True
+(will commit the changes). Useful when the user does not want to commit
+after each change, but after a couple.
.UNINDENT
-.TP
-.B Commit commit (bool)
-commit loaded config. By default \fIcommit\fP is True (will commit the changes). Useful when
.UNINDENT
.sp
-the user does not want to commit after each change, but after a couple.
-.sp
-By default this function will commit the config changes (if any). To load without committing, use the \fIcommit\fP
-option. For dry run use the \fItest\fP argument.
+By default this function will commit the config changes (if any). To load
+without committing, use the \fBcommit\fP option. For dry run use the \fBtest\fP
+argument.
.sp
CLI Example:
.INDENT 7.0
@@ -182516,15 +191746,16 @@ Configures a list of NTP peers on the device.
.IP \(bu 2
\fBpeers\fP \-\- list of IP Addresses/Domain Names
.IP \(bu 2
-\fB(bool)\fP (\fItest\fP) \-\- discard loaded config. By default \fItest\fP is False (will not dicard the changes)
+\fB(bool)\fP (\fItest\fP) \-\- discard loaded config. By default \fItest\fP is False (will
+not dicard the changes)
.UNINDENT
.TP
.B Commit commit (bool)
-commit loaded config. By default \fIcommit\fP is True (will commit the changes). Useful when
+commit loaded config. By default \fIcommit\fP is True
+(will commit the changes). Useful when the user does not want to commit
+after each change, but after a couple.
.UNINDENT
.sp
-the user does not want to commit after each change, but after a couple.
-.sp
By default this function will commit the config changes (if any). To load without committing, use the \fIcommit\fP
option. For dry run use the \fItest\fP argument.
.sp
@@ -182557,11 +191788,11 @@ Configures a list of NTP servers on the device.
.UNINDENT
.TP
.B Commit commit (bool)
-commit loaded config. By default \fIcommit\fP is True (will commit the changes). Useful when
+commit loaded config. By default \fIcommit\fP is True
+(will commit the changes). Useful when the user does not want to commit
+after each change, but after a couple.
.UNINDENT
.sp
-the user does not want to commit after each change, but after a couple.
-.sp
By default this function will commit the config changes (if any). To load without committing, use the \fIcommit\fP
option. For dry run use the \fItest\fP argument.
.sp
@@ -182690,6 +191921,11 @@ unix
.sp
New in version 2016.11.0.
+.INDENT 0.0
+.TP
+.B salt.modules.napalm_probes.__virtual__()
+NAPALM library must be installed for this module to work and run in a (proxy) minion.
+.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.napalm_probes.config(*args, **kwargs)
@@ -182751,37 +191987,40 @@ from the configuration of the device.
.INDENT 7.0
.TP
.B Parameters
-\fBprobes\fP \-\- Dictionary with a similar format as the output dictionary of the function config(),
-.UNINDENT
-.sp
-where the details are not necessary.
-:param test: Dry run? If set as True, will apply the config, discard and return the changes. Default: False
-and will commit the changes on the device.
-:param commit: Commit? (default: True) Sometimes it is not needed to commit the config immediately
.INDENT 7.0
-.INDENT 3.5
-after loading the changes. E.g.: a state loads a couple of parts (add / remove / update)
-and would not be optimal to commit after each operation.
-Also, from the CLI when the user needs to apply the similar changes before committing,
-can specify commit=False and will not discard the config.
+.IP \(bu 2
+\fBprobes\fP \-\- Dictionary with a similar format as the output dictionary of
+the function config(), where the details are not necessary.
+.IP \(bu 2
+\fBtest\fP \-\- Dry run? If set as True, will apply the config, discard and
+return the changes. Default: False
+.IP \(bu 2
+\fBcommit\fP \-\- Commit? (default: True) Sometimes it is not needed to commit
+the config immediately after loading the changes. E.g.: a state loads a
+couple of parts (add / remove / update) and would not be optimal to
+commit after each operation. Also, from the CLI when the user needs to
+apply the similar changes before committing, can specify commit=False
+and will not discard the config.
.UNINDENT
-.UNINDENT
-.INDENT 7.0
.TP
.B Raises
\fBMergeConfigException\fP \-\- If there is an error on the configuration sent.
.TP
-.B Return a dictionary having the following keys
+.B Returns
+A dictionary having the following keys:
+.UNINDENT
.INDENT 7.0
.IP \(bu 2
-result (bool): if the config was applied successfully. It is \fIFalse\fP only in case of failure. In case
-.UNINDENT
-.sp
-there are no changes to be applied and successfully performs all operations it is still \fITrue\fP and so will be
+result (bool): if the config was applied successfully. It is \fIFalse\fP only
+in case of failure. In case there are no changes to be applied and
+successfully performs all operations it is still \fITrue\fP and so will be
the \fIalready_configured\fP flag (example below)
-* comment (str): a message for the user
-* already_configured (bool): flag to check if there were no changes applied
-* diff (str): returns the config changes applied
+.IP \(bu 2
+comment (str): a message for the user
+.IP \(bu 2
+already_configured (bool): flag to check if there were no changes applied
+.IP \(bu 2
+diff (str): returns the config changes applied
.UNINDENT
.sp
Input example:
@@ -182874,44 +192113,49 @@ Output example:
.INDENT 0.0
.TP
.B salt.modules.napalm_probes.schedule_probes(*args, **kwargs)
-Will schedule the probes. On Cisco devices, it is not enough to define the probes, it is also necessary
-to schedule them.
-This method calls the configuration template \(aqschedule_probes\(aq from the NAPALM library,
-providing as input a rich formatted dictionary with the names of the probes and the tests to be scheduled.
+Will schedule the probes. On Cisco devices, it is not enough to define the
+probes, it is also necessary to schedule them.
+.sp
+This function calls the configuration template \fBschedule_probes\fP from the
+NAPALM library, providing as input a rich formatted dictionary with the
+names of the probes and the tests to be scheduled.
.INDENT 7.0
.TP
.B Parameters
-\fBprobes\fP \-\- Dictionary with a similar format as the output dictionary of the function config(),
-.UNINDENT
-.sp
-where the details are not necessary.
-:param test: Dry run? If set as True, will apply the config, discard and return the changes. Default: False
-and will commit the changes on the device.
-:param commit: Commit? (default: True) Sometimes it is not needed to commit the config immediately
.INDENT 7.0
-.INDENT 3.5
-after loading the changes. E.g.: a state loads a couple of parts (add / remove / update)
-and would not be optimal to commit after each operation.
-Also, from the CLI when the user needs to apply the similar changes before committing,
-can specify commit=False and will not discard the config.
+.IP \(bu 2
+\fBprobes\fP \-\- Dictionary with a similar format as the output dictionary of
+the function config(), where the details are not necessary.
+.IP \(bu 2
+\fBtest\fP \-\- Dry run? If set as True, will apply the config, discard and
+return the changes. Default: False
+.IP \(bu 2
+\fBcommit\fP \-\- Commit? (default: True) Sometimes it is not needed to commit
+the config immediately after loading the changes. E.g.: a state loads a
+couple of parts (add / remove / update) and would not be optimal to
+commit after each operation. Also, from the CLI when the user needs to
+apply the similar changes before committing, can specify commit=False
+and will not discard the config.
.UNINDENT
-.UNINDENT
-.INDENT 7.0
.TP
.B Raises
\fBMergeConfigException\fP \-\- If there is an error on the configuration sent.
.TP
-.B Return a dictionary having the following keys
+.B Returns
+a dictionary having the following keys:
+.UNINDENT
.INDENT 7.0
.IP \(bu 2
-result (bool): if the config was applied successfully. It is \fIFalse\fP only in case of failure. In case
-.UNINDENT
-.sp
-there are no changes to be applied and successfully performs all operations it is still \fITrue\fP and so will be
+result (bool): if the config was applied successfully. It is \fIFalse\fP only
+in case of failure. In case there are no changes to be applied and
+successfully performs all operations it is still \fITrue\fP and so will be
the \fIalready_configured\fP flag (example below)
-* comment (str): a message for the user
-* already_configured (bool): flag to check if there were no changes applied
-* diff (str): returns the config changes applied
+.IP \(bu 2
+comment (str): a message for the user
+.IP \(bu 2
+already_configured (bool): flag to check if there were no changes applied
+.IP \(bu 2
+diff (str): returns the config changes applied
.UNINDENT
.sp
Input example:
@@ -182945,20 +192189,14 @@ providing as input a rich formatted dictionary with the configuration details of
\fBprobes\fP \-\- Dictionary formatted as the output of the function config()
.IP \(bu 2
\fBtest\fP \-\- Dry run? If set as True, will apply the config, discard and return the changes. Default: False
+.IP \(bu 2
+\fBcommit\fP \-\- Commit? (default: True) Sometimes it is not needed to commit
+the config immediately after loading the changes. E.g.: a state loads a
+couple of parts (add / remove / update) and would not be optimal to
+commit after each operation. Also, from the CLI when the user needs to
+apply the similar changes before committing, can specify commit=False
+and will not discard the config.
.UNINDENT
-.UNINDENT
-.sp
-and will commit the changes on the device.
-:param commit: Commit? (default: True) Sometimes it is not needed to commit the config immediately
-.INDENT 7.0
-.INDENT 3.5
-after loading the changes. E.g.: a state loads a couple of parts (add / remove / update)
-and would not be optimal to commit after each operation.
-Also, from the CLI when the user needs to apply the similar changes before committing,
-can specify commit=False and will not discard the config.
-.UNINDENT
-.UNINDENT
-.INDENT 7.0
.TP
.B Raises
\fBMergeConfigException\fP \-\- If there is an error on the configuration sent.
@@ -182966,14 +192204,17 @@ can specify commit=False and will not discard the config.
.B Return a dictionary having the following keys
.INDENT 7.0
.IP \(bu 2
-result (bool): if the config was applied successfully. It is \fIFalse\fP only in case of failure. In case
+result (bool): if the config was applied successfully. It is \fIFalse\fP
+only in case of failure. In case there are no changes to be applied
+and successfully performs all operations it is still \fITrue\fP and so
+will be the \fIalready_configured\fP flag (example below)
+.IP \(bu 2
+comment (str): a message for the user
+.IP \(bu 2
+already_configured (bool): flag to check if there were no changes applied
+.IP \(bu 2
+diff (str): returns the config changes applied
.UNINDENT
-.sp
-there are no changes to be applied and successfully performs all operations it is still \fITrue\fP and so will be
-the \fIalready_configured\fP flag (example below)
-* comment (str): a message for the user
-* already_configured (bool): flag to check if there were no changes applied
-* diff (str): returns the config changes applied
.UNINDENT
.sp
Input example \- via state/script:
@@ -183075,6 +192316,11 @@ unix
.sp
New in version 2016.11.0.
+.INDENT 0.0
+.TP
+.B salt.modules.napalm_route.__virtual__()
+NAPALM library must be installed for this module to work and run in a (proxy) minion.
+.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.napalm_route.show(*args, **kwargs)
@@ -183219,6 +192465,11 @@ unix
.sp
New in version 2016.11.0.
+.INDENT 0.0
+.TP
+.B salt.modules.napalm_snmp.__virtual__()
+NAPALM library must be installed for this module to work and run in a (proxy) minion.
+.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.napalm_snmp.config(*args, **kwargs)
@@ -183248,43 +192499,51 @@ Removes a configuration element from the SNMP configuration.
\fBchassis_id\fP \-\- (optional) Chassis ID
.IP \(bu 2
\fBcommunity\fP \-\- (optional) A dictionary having the following optional keys:
-* acl (if any policy / ACL need to be set)
-* mode: rw or ro. Default: ro
+.UNINDENT
+.UNINDENT
+.INDENT 7.0
+.IP \(bu 2
+acl (if any policy / ACL need to be set)
+.IP \(bu 2
+mode: rw or ro. Default: ro
+.UNINDENT
+.INDENT 7.0
+.TP
+.B Parameters
+.INDENT 7.0
.IP \(bu 2
\fBcontact\fP \-\- Contact details
.IP \(bu 2
\fBlocation\fP \-\- Location
.IP \(bu 2
\fBtest\fP \-\- Dry run? If set as True, will apply the config, discard and return the changes. Default: False
+.IP \(bu 2
+\fBcommit\fP \-\- Commit? (default: True) Sometimes it is not needed to commit
+the config immediately after loading the changes. E.g.: a state loads a
+couple of parts (add / remove / update) and would not be optimal to
+commit after each operation. Also, from the CLI when the user needs to
+apply the similar changes before committing, can specify commit=False
+and will not discard the config.
.UNINDENT
-.UNINDENT
-.sp
-and will commit the changes on the device.
-:param commit: Commit? (default: True) Sometimes it is not needed to commit the config immediately
-.INDENT 7.0
-.INDENT 3.5
-after loading the changes. E.g.: a state loads a couple of parts (add / remove / update)
-and would not be optimal to commit after each operation.
-Also, from the CLI when the user needs to apply the similar changes before committing,
-can specify commit=False and will not discard the config.
-.UNINDENT
-.UNINDENT
-.INDENT 7.0
.TP
.B Raises
\fBMergeConfigException\fP \-\- If there is an error on the configuration sent.
.TP
-.B Return a dictionary having the following keys
+.B Returns
+A dictionary having the following keys:
+.UNINDENT
.INDENT 7.0
.IP \(bu 2
-result (bool): if the config was applied successfully. It is \fIFalse\fP only in case of failure. In case
-.UNINDENT
-.sp
-there are no changes to be applied and successfully performs all operations it is still \fITrue\fP and so will be
-the \fIalready_configured\fP flag (example below)
-* comment (str): a message for the user
-* already_configured (bool): flag to check if there were no changes applied
-* diff (str): returns the config changes applied
+result (bool): if the config was applied successfully. It is \fIFalse\fP
+only in case of failure. In case there are no changes to be applied
+and successfully performs all operations it is still \fITrue\fP and so
+will be the \fIalready_configured\fP flag (example below)
+.IP \(bu 2
+comment (str): a message for the user
+.IP \(bu 2
+already_configured (bool): flag to check if there were no changes applied
+.IP \(bu 2
+diff (str): returns the config changes applied
.UNINDENT
.sp
CLI Example:
@@ -183311,43 +192570,49 @@ Updates the SNMP configuration.
\fBchassis_id\fP \-\- (optional) Chassis ID
.IP \(bu 2
\fBcommunity\fP \-\- (optional) A dictionary having the following optional keys:
-* acl (if any policy / ACL need to be set)
-* mode: rw or ro. Default: ro
+.UNINDENT
+.UNINDENT
+.INDENT 7.0
+.IP \(bu 2
+acl (if any policy / ACL need to be set)
+.IP \(bu 2
+mode: rw or ro. Default: ro
+.UNINDENT
+.INDENT 7.0
+.TP
+.B Parameters
+.INDENT 7.0
.IP \(bu 2
\fBcontact\fP \-\- Contact details
.IP \(bu 2
\fBlocation\fP \-\- Location
.IP \(bu 2
\fBtest\fP \-\- Dry run? If set as True, will apply the config, discard and return the changes. Default: False
-.UNINDENT
-.UNINDENT
-.sp
-and will commit the changes on the device.
-:param commit: Commit? (default: True) Sometimes it is not needed to commit the config immediately
-.INDENT 7.0
-.INDENT 3.5
+.IP \(bu 2
+\fBcommit\fP \-\- Commit? (default: True) Sometimes it is not needed to commit the config immediately
after loading the changes. E.g.: a state loads a couple of parts (add / remove / update)
and would not be optimal to commit after each operation.
Also, from the CLI when the user needs to apply the similar changes before committing,
can specify commit=False and will not discard the config.
.UNINDENT
-.UNINDENT
-.INDENT 7.0
.TP
.B Raises
\fBMergeConfigException\fP \-\- If there is an error on the configuration sent.
.TP
.B Return a dictionary having the following keys
+.UNINDENT
.INDENT 7.0
.IP \(bu 2
-result (bool): if the config was applied successfully. It is \fIFalse\fP only in case of failure. In case
-.UNINDENT
-.sp
-there are no changes to be applied and successfully performs all operations it is still \fITrue\fP and so will be
+result (bool): if the config was applied successfully. It is \fIFalse\fP only
+in case of failure. In case there are no changes to be applied and
+successfully performs all operations it is still \fITrue\fP and so will be
the \fIalready_configured\fP flag (example below)
-* comment (str): a message for the user
-* already_configured (bool): flag to check if there were no changes applied
-* diff (str): returns the config changes applied
+.IP \(bu 2
+comment (str): a message for the user
+.IP \(bu 2
+already_configured (bool): flag to check if there were no changes applied
+.IP \(bu 2
+diff (str): returns the config changes applied
.UNINDENT
.sp
CLI Example:
@@ -183418,6 +192683,11 @@ unix
.sp
New in version 2016.11.0.
+.INDENT 0.0
+.TP
+.B salt.modules.napalm_users.__virtual__()
+NAPALM library must be installed for this module to work and run in a (proxy) minion.
+.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.napalm_users.config(*args, **kwargs)
@@ -183467,20 +192737,13 @@ Removes users from the configuration of network devices.
\fBusers\fP \-\- Dictionary formatted as the output of the function config()
.IP \(bu 2
\fBtest\fP \-\- Dry run? If set as True, will apply the config, discard and return the changes. Default: False
-.UNINDENT
-.UNINDENT
-.sp
-and will commit the changes on the device.
-:param commit: Commit? (default: True) Sometimes it is not needed to commit the config immediately
-.INDENT 7.0
-.INDENT 3.5
+.IP \(bu 2
+\fBcommit\fP \-\- Commit? (default: True) Sometimes it is not needed to commit the config immediately
after loading the changes. E.g.: a state loads a couple of parts (add / remove / update)
and would not be optimal to commit after each operation.
Also, from the CLI when the user needs to apply the similar changes before committing,
can specify commit=False and will not discard the config.
.UNINDENT
-.UNINDENT
-.INDENT 7.0
.TP
.B Raises
\fBMergeConfigException\fP \-\- If there is an error on the configuration sent.
@@ -183488,14 +192751,17 @@ can specify commit=False and will not discard the config.
.B Return a dictionary having the following keys
.INDENT 7.0
.IP \(bu 2
-result (bool): if the config was applied successfully. It is \fIFalse\fP only in case of failure. In case
+result (bool): if the config was applied successfully. It is \fIFalse\fP
+only in case of failure. In case there are no changes to be applied
+and successfully performs all operations it is still \fITrue\fP and so
+will be the \fIalready_configured\fP flag (example below)
+.IP \(bu 2
+comment (str): a message for the user
+.IP \(bu 2
+already_configured (bool): flag to check if there were no changes applied
+.IP \(bu 2
+diff (str): returns the config changes applied
.UNINDENT
-.sp
-there are no changes to be applied and successfully performs all operations it is still \fITrue\fP and so will be
-the \fIalready_configured\fP flag (example below)
-* comment (str): a message for the user
-* already_configured (bool): flag to check if there were no changes applied
-* diff (str): returns the config changes applied
.UNINDENT
.sp
CLI Example:
@@ -183521,36 +192787,34 @@ Configures users on network devices.
.IP \(bu 2
\fBusers\fP \-\- Dictionary formatted as the output of the function config()
.IP \(bu 2
-\fBtest\fP \-\- Dry run? If set as True, will apply the config, discard and return the changes. Default: False
+\fBtest\fP \-\- Dry run? If set as True, will apply the config, discard and
+return the changes. Default: False
+.IP \(bu 2
+\fBcommit\fP \-\- Commit? (default: True) Sometimes it is not needed to commit
+the config immediately after loading the changes. E.g.: a state loads a
+couple of parts (add / remove / update) and would not be optimal to
+commit after each operation. Also, from the CLI when the user needs to
+apply the similar changes before committing, can specify commit=False
+and will not discard the config.
.UNINDENT
-.UNINDENT
-.sp
-and will commit the changes on the device.
-:param commit: Commit? (default: True) Sometimes it is not needed to commit the config immediately
-.INDENT 7.0
-.INDENT 3.5
-after loading the changes. E.g.: a state loads a couple of parts (add / remove / update)
-and would not be optimal to commit after each operation.
-Also, from the CLI when the user needs to apply the similar changes before committing,
-can specify commit=False and will not discard the config.
-.UNINDENT
-.UNINDENT
-.INDENT 7.0
.TP
.B Raises
\fBMergeConfigException\fP \-\- If there is an error on the configuration sent.
.TP
.B Return a dictionary having the following keys
+.UNINDENT
.INDENT 7.0
.IP \(bu 2
-result (bool): if the config was applied successfully. It is \fIFalse\fP only in case of failure. In case
-.UNINDENT
-.sp
-there are no changes to be applied and successfully performs all operations it is still \fITrue\fP and so will be
+result (bool): if the config was applied successfully. It is \fIFalse\fP only
+in case of failure. In case there are no changes to be applied and
+successfully performs all operations it is still \fITrue\fP and so will be
the \fIalready_configured\fP flag (example below)
-* comment (str): a message for the user
-* already_configured (bool): flag to check if there were no changes applied
-* diff (str): returns the config changes applied
+.IP \(bu 2
+comment (str): a message for the user
+.IP \(bu 2
+already_configured (bool): flag to check if there were no changes applied
+.IP \(bu 2
+diff (str): returns the config changes applied
.UNINDENT
.sp
CLI Example:
@@ -183572,6 +192836,12 @@ NAPALM YANG basic operations.
.sp
New in version 2017.7.0.
+.INDENT 0.0
+.TP
+.B salt.modules.napalm_yang_mod.__virtual__()
+NAPALM library must be installed for this module to work and run in a (proxy) minion.
+This module in particular requires also napalm\-yang.
+.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.napalm_yang_mod.compliance_report(*args, **kwargs)
@@ -184134,6 +193404,11 @@ netaddr
.UNINDENT
.INDENT 0.0
.TP
+.B salt.modules.netaddress.__virtual__()
+Only load if netaddr library exist.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.netaddress.cidr_broadcast(cidr)
Get the broadcast address associated with a CIDR address.
.sp
@@ -184205,6 +193480,11 @@ salt myminion netaddress.list_cidr_ips_ipv6 192.168.0.0/20
Module for viewing and modifying sysctl parameters
.INDENT 0.0
.TP
+.B salt.modules.netbsd_sysctl.__virtual__()
+Only run on NetBSD systems
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.netbsd_sysctl.assign(name, value)
Assign a single sysctl parameter for this minion
.sp
@@ -184285,6 +193565,11 @@ minion, and it is using a different module (or gives an error similar to
.UNINDENT
.INDENT 0.0
.TP
+.B salt.modules.netbsdservice.__virtual__()
+Only work on NetBSD
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.netbsdservice.available(name)
Returns \fBTrue\fP if the specified service is available, otherwise returns
\fBFalse\fP\&.
@@ -184617,6 +193902,11 @@ salt\-call netscaler.server_up server_name3 netscaler_host=1.2.3.6 netscaler_use
.UNINDENT
.INDENT 0.0
.TP
+.B salt.modules.netscaler.__virtual__()
+Only load this module if the nsnitro library is installed
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.netscaler.server_add(s_name, s_ip, s_state=None, **connection_args)
Add a server
Note: The default server state is ENABLED
@@ -185120,6 +194410,11 @@ salt \(aq*\(aq netscaler.vserver_sslcert_exists \(aqvserverName\(aq \(aqsslCerti
Module for gathering and managing network information
.INDENT 0.0
.TP
+.B salt.modules.network.__virtual__()
+Only work on POSIX\-like systems
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.network.active_tcp()
Return a dict containing information on all of the running TCP connections (currently linux and solaris only)
.sp
@@ -186005,6 +195300,12 @@ None to allow keystoneauth to search for the certificates on its own.(defaults t
.UNINDENT
.INDENT 0.0
.TP
+.B salt.modules.neutron.__virtual__()
+Only load this module if neutron
+is installed on this minion.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.neutron.add_gateway_router(router, ext_network, profile=None)
Adds an external network gateway to the specified router
.sp
@@ -187997,13 +197298,15 @@ salt \(aq*\(aq neutron.update_floatingip network\-name port\-name
.IP \(bu 2
\fBfloatingip_id\fP \-\- ID of floatingIP
.IP \(bu 2
-\fBport\fP \-\- ID or name of port, to associate floatingip to
+\fBport\fP \-\- ID or name of port, to associate floatingip to \fINone\fP or do
+not specify to disassociate the floatingip (Optional)
+.IP \(bu 2
+\fBprofile\fP \-\- Profile to build on (Optional)
.UNINDENT
+.TP
+.B Returns
+Value of updated floating IP information
.UNINDENT
-.sp
-\fINone\fP or do not specify to disassociate the floatingip (Optional)
-:param profile: Profile to build on (Optional)
-:return: Value of updated floating IP information
.UNINDENT
.INDENT 0.0
.TP
@@ -188260,6 +197563,11 @@ Value of updated VPN service information
Module for managing NFS version 3.
.INDENT 0.0
.TP
+.B salt.modules.nfs3.__virtual__()
+Only work on POSIX\-like systems
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.nfs3.del_export(exports=\(aq/etc/exports\(aq, path=None)
Remove an export
.sp
@@ -188297,6 +197605,11 @@ salt \(aq*\(aq nfs.list_exports
Support for nftables
.INDENT 0.0
.TP
+.B salt.modules.nftables.__virtual__()
+Only load the module if nftables is installed
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.nftables.append(table=\(aqfilter\(aq, chain=None, rule=None, family=\(aqipv4\(aq)
Append a rule to the specified table & chain.
.INDENT 7.0
@@ -188743,6 +198056,11 @@ salt \(aq*\(aq nftables.version
Support for nginx
.INDENT 0.0
.TP
+.B salt.modules.nginx.__virtual__()
+Only load the module if nginx is installed
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.nginx.build_info()
Return server and build arguments
.sp
@@ -188837,14 +198155,23 @@ salt \(aq*\(aq nginx.version
The networking module for NI Linux Real\-Time distro
.INDENT 0.0
.TP
+.B salt.modules.nilrt_ip.__virtual__()
+Confine this module to NI Linux Real\-Time based distros
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.nilrt_ip.apply_network_settings(**settings)
Apply global network configuration.
.sp
CLI Example:
-.. code\-block:: bash
.INDENT 7.0
.INDENT 3.5
+.sp
+.nf
+.ft C
salt \(aq*\(aq ip.apply_network_settings
+.ft P
+.fi
.UNINDENT
.UNINDENT
.UNINDENT
@@ -188854,10 +198181,14 @@ salt \(aq*\(aq ip.apply_network_settings
Build an interface script for a network interface.
.sp
CLI Example:
-.. code\-block:: bash
.INDENT 7.0
.INDENT 3.5
+.sp
+.nf
+.ft C
salt \(aq*\(aq ip.build_interface eth0 eth
+.ft P
+.fi
.UNINDENT
.UNINDENT
.UNINDENT
@@ -188867,10 +198198,14 @@ salt \(aq*\(aq ip.build_interface eth0 eth
Build the global network script.
.sp
CLI Example:
-.. code\-block:: bash
.INDENT 7.0
.INDENT 3.5
+.sp
+.nf
+.ft C
salt \(aq*\(aq ip.build_network_settings
+.ft P
+.fi
.UNINDENT
.UNINDENT
.UNINDENT
@@ -189006,10 +198341,14 @@ salt \(aq*\(aq ip.get_interfaces_details
Return the contents of the global network script.
.sp
CLI Example:
-.. code\-block:: bash
.INDENT 7.0
.INDENT 3.5
+.sp
+.nf
+.ft C
salt \(aq*\(aq ip.get_network_settings
+.ft P
+.fi
.UNINDENT
.UNINDENT
.UNINDENT
@@ -189114,15 +198453,22 @@ salt \(aq*\(aq ip.up interface\-label
New in version 2017.7.0.
.sp
-Does not require the machine to be Nixos, just have Nix installed and available to use for the user running this command. Their profile must
-be located in their home, under \fB$HOME/.nix\-profile/\fP, and the nix store, unless specially set up, should be in \fB/nix\fP\&. To easily use this
-with multiple users or a root user, set up the \&.
+Does not require the machine to be Nixos, just have Nix installed and available
+to use for the user running this command. Their profile must be located in
+their home, under \fB$HOME/.nix\-profile/\fP, and the nix store, unless specially
+set up, should be in \fB/nix\fP\&. To easily use this with multiple users or a root
+user, set up the \fI\%nix\-daemon\fP\&.
.sp
This module exposes most of the common nix operations. Currently not meant to be run as a \fBpkg\fP module, but explicitly as \fBnix.*\fP\&.
.sp
For more information on nix, see the \fI\%nix documentation\fP\&.
.INDENT 0.0
.TP
+.B salt.modules.nix.__virtual__()
+This only works if we have access to nix\-env
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.nix.collect_garbage()
Completely removed all currently \(aquninstalled\(aq packages in the nix store.
.sp
@@ -189350,7 +198696,7 @@ option in the pillar or minion config.
\fBNOTE:\fP
.INDENT 7.0
.INDENT 3.5
-this is required to use keystone v3 as for authentication.
+This is required to use keystone v3 as for authentication.
.UNINDENT
.UNINDENT
.INDENT 7.0
@@ -189369,12 +198715,25 @@ keystone.verify: \(aq/path/to/custom/certs/ca\-bundle.crt\(aq
.UNINDENT
.UNINDENT
.sp
-Note: by default the nova module will attempt to verify its connection
-utilizing the system certificates. If you need to verify against another bundle
-of CA certificates or want to skip verification altogether you will need to
-specify the \fIverify\fP option. You can specify True or False to verify (or not)
-against system certificates, a path to a bundle or CA certs to check against, or
-None to allow keystoneauth to search for the certificates on its own.(defaults to True)
+\fBNOTE:\fP
+.INDENT 7.0
+.INDENT 3.5
+By default the nova module will attempt to verify its connection
+utilizing the system certificates. If you need to verify against
+another bundle of CA certificates or want to skip verification
+altogether you will need to specify the \fIverify\fP option. You can
+specify True or False to verify (or not) against system certificates, a
+path to a bundle or CA certs to check against, or None to allow
+keystoneauth to search for the certificates on its own. (defaults to
+True)
+.UNINDENT
+.UNINDENT
+.UNINDENT
+.INDENT 0.0
+.TP
+.B salt.modules.nova.__virtual__()
+Only load this module if nova
+is installed on this minion.
.UNINDENT
.INDENT 0.0
.TP
@@ -189476,7 +198835,7 @@ CLI Example:
.sp
.nf
.ft C
-salt \(aq*\(aq nova.flavor_create myflavor flavor_id=6 ram=4096 disk=10 vcpus=1
+salt \(aq*\(aq nova.flavor_create myflavor flavor_id=6 ram=4096 disk=10 vcpus=1
.ft P
.fi
.UNINDENT
@@ -189547,7 +198906,7 @@ CLI Examples:
.sp
.nf
.ft C
-salt \(aq*\(aq nova.image_meta_delete 6f52b2ff\-0b31\-4d84\-8fd1\-af45b84824f6 keys=cheese
+salt \(aq*\(aq nova.image_meta_delete 6f52b2ff\-0b31\-4d84\-8fd1\-af45b84824f6 keys=cheese
salt \(aq*\(aq nova.image_meta_delete name=myimage keys=salad,beans
.ft P
.fi
@@ -189565,7 +198924,7 @@ CLI Examples:
.sp
.nf
.ft C
-salt \(aq*\(aq nova.image_meta_set 6f52b2ff\-0b31\-4d84\-8fd1\-af45b84824f6 cheese=gruyere
+salt \(aq*\(aq nova.image_meta_set 6f52b2ff\-0b31\-4d84\-8fd1\-af45b84824f6 cheese=gruyere
salt \(aq*\(aq nova.image_meta_set name=myimage salad=pasta beans=baked
.ft P
.fi
@@ -189583,7 +198942,7 @@ CLI Examples:
.sp
.nf
.ft C
-salt \(aq*\(aq nova.keypair_add mykey pubfile=\(aq/home/myuser/.ssh/id_rsa.pub\(aq
+salt \(aq*\(aq nova.keypair_add mykey pubfile=/home/myuser/.ssh/id_rsa.pub
salt \(aq*\(aq nova.keypair_add mykey pubkey=\(aqssh\-rsa myuser@mybox\(aq
.ft P
.fi
@@ -189601,7 +198960,7 @@ CLI Example:
.sp
.nf
.ft C
-salt \(aq*\(aq nova.keypair_delete mykey\(aq
+salt \(aq*\(aq nova.keypair_delete mykey
.ft P
.fi
.UNINDENT
@@ -189876,7 +199235,7 @@ CLI Example:
.nf
.ft C
salt \(aq*\(aq nova.volume_attach myblock slice.example.com profile=openstack
-salt \(aq*\(aq nova.volume_attach myblock server.example.com device=\(aq/dev/xvdb\(aq profile=openstack
+salt \(aq*\(aq nova.volume_attach myblock server.example.com device=/dev/xvdb profile=openstack
.ft P
.fi
.UNINDENT
@@ -189988,7 +199347,7 @@ CLI Example:
.sp
.nf
.ft C
-salt \(aq*\(aq nova.volume_list search_opts=\(aq{"display_name": "myblock"}\(aq profile=openstack
+salt \(aq*\(aq nova.volume_list search_opts=\(aq{"display_name": "myblock"}\(aq profile=openstack
.ft P
.fi
.UNINDENT
@@ -190024,6 +199383,11 @@ salt \(aq*\(aq nova.volume_show myblock profile=openstack
Manage and query NPM packages.
.INDENT 0.0
.TP
+.B salt.modules.npm.__virtual__()
+Only work when npm is installed.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.npm.cache_clean(path=None, runas=None, env=None, force=False)
Clean cached NPM packages.
.sp
@@ -190297,6 +199661,11 @@ Minions running systemd >= 219 will place new containers in
\fB/var/lib/container\fP\&.
.INDENT 0.0
.TP
+.B salt.modules.nspawn.__virtual__()
+Only work on systems that have been booted with systemd
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.nspawn.bootstrap_container(name, dist=None, version=None)
Bootstrap a container from package servers, if dist is None the os the
minion is running as will be created, otherwise the needed bootstrapping
@@ -191184,6 +200553,11 @@ pypureomapi Python module
.UNINDENT
.INDENT 0.0
.TP
+.B salt.modules.omapi.__virtual__()
+Confirm pypureomapi is available.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.omapi.add_host(mac, name=None, ip=None, ddns=False, group=None, supersede_host=False)
Add a host object for the given mac.
.sp
@@ -191234,6 +200608,11 @@ salt dhcp\-server omapi.delete_host mac=ab:ab:ab:ab:ab:ab
Module for viewing and modifying OpenBSD sysctl parameters
.INDENT 0.0
.TP
+.B salt.modules.openbsd_sysctl.__virtual__()
+Only run on OpenBSD systems
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.openbsd_sysctl.assign(name, value)
Assign a single sysctl parameter for this minion
.sp
@@ -191329,6 +200708,11 @@ default branch by default. Examples:
.UNINDENT
.UNINDENT
+.INDENT 0.0
+.TP
+.B salt.modules.openbsdpkg.__virtual__()
+Set the virtual pkg module if the os is OpenBSD
+.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.openbsdpkg.install(name=None, pkgs=None, sources=None, **kwargs)
@@ -191523,6 +200907,11 @@ salt \(aq*\(aq pkg.version ...
The rcctl service module for OpenBSD
.INDENT 0.0
.TP
+.B salt.modules.openbsdrcctl.__virtual__()
+rcctl(8) is only available on OpenBSD.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.openbsdrcctl.available(name)
Return True if the named service is available.
.sp
@@ -191791,6 +201180,11 @@ minion, and it is using a different module (or gives an error similar to
.UNINDENT
.INDENT 0.0
.TP
+.B salt.modules.openbsdservice.__virtual__()
+Only work on OpenBSD
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.openbsdservice.available(name)
New in version 2014.7.0.
@@ -192166,6 +201560,11 @@ linux
.UNINDENT
.INDENT 0.0
.TP
+.B salt.modules.openstack_mng.__virtual__()
+Only load this module if openstack\-service is installed
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.openstack_mng.restart_service(service_name, minimum_running_time=None)
Restart OpenStack service immediately, or only if it\(aqs running longer than
specified value
@@ -192229,6 +201628,11 @@ Jiri Kotlin <\fI\%jiri.kotlin@ultimum.io\fP>
.UNINDENT
.INDENT 0.0
.TP
+.B salt.modules.openvswitch.__virtual__()
+Only load the module if Open vSwitch is installed
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.openvswitch.bridge_create(br, may_exist=True)
Creates a new bridge.
.INDENT 7.0
@@ -192612,6 +202016,11 @@ must be installed.
.UNINDENT
.INDENT 0.0
.TP
+.B salt.modules.opkg.__virtual__()
+Confirm this module is on a nilrt based system
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.opkg.available_version(*names, **kwargs)
Return the latest version of the named package available for upgrade or
installation. If more than one package name is specified, a dict of
@@ -192637,11 +202046,7 @@ salt \(aq*\(aq pkg.latest_version ...
.INDENT 0.0
.TP
.B salt.modules.opkg.del_repo(alias, **kwargs)
-Delete a repo from /etc/opkg/
-.nf
-*
-.fi
-\&.conf
+Delete a repo from \fB/etc/opkg/*.conf\fP
.sp
If the file does not contain any other repo configuration, the file itself
will be deleted.
@@ -192703,11 +202108,7 @@ salt \(aq*\(aq pkg.file_list
.INDENT 0.0
.TP
.B salt.modules.opkg.get_repo(alias, **kwargs)
-Display a repo from the /etc/opkg/
-.nf
-*
-.fi
-\&.conf
+Display a repo from the \fB/etc/opkg/*.conf\fP
.sp
CLI Examples:
.INDENT 7.0
@@ -192970,11 +202371,7 @@ salt \(aq*\(aq pkg.list_pkgs versions_as_list=True
.INDENT 0.0
.TP
.B salt.modules.opkg.list_repos(**kwargs)
-Lists all repos on /etc/opkg/
-.nf
-*
-.fi
-\&.conf
+Lists all repos on \fB/etc/opkg/*.conf\fP
.sp
CLI Example:
.INDENT 7.0
@@ -193340,6 +202737,11 @@ oracle.dbs..uri: connection credentials in format:
.UNINDENT
.INDENT 0.0
.TP
+.B salt.modules.oracle.__virtual__()
+Load module only if cx_Oracle installed
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.oracle.client_version()
Oracle Client Version
.sp
@@ -194678,6 +204080,11 @@ minion, and it is using a different module (or gives an error similar to
.UNINDENT
.INDENT 0.0
.TP
+.B salt.modules.pacman.__virtual__()
+Set the virtual pkg module if the os is Arch
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.pacman.file_dict(*packages)
List the files that belong to a package, grouped by package. Not
specifying any packages will return a list of _every_ file on the system\(aqs
@@ -195274,6 +204681,11 @@ my\-pagerduty\-account:
.UNINDENT
.INDENT 0.0
.TP
+.B salt.modules.pagerduty.__virtual__()
+No dependencies outside of what Salt itself requires
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.pagerduty.create_event(service_key=None, description=None, details=None, incident_key=None, profile=None)
Create an event in PagerDuty. Designed for use in states.
.sp
@@ -195444,6 +204856,11 @@ pagerduty:
For PagerDuty API details, see \fI\%https://developer.pagerduty.com/documentation/rest\fP
.INDENT 0.0
.TP
+.B salt.modules.pagerduty_util.__virtual__()
+No dependencies outside of what Salt itself requires
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.pagerduty_util.create_or_update_resource(resource_name, identifier_fields, data, diff=None, profile=\(aqpagerduty\(aq, subdomain=None, api_key=None)
create or update any pagerduty resource
Helper method for present().
@@ -195565,6 +204982,11 @@ resource_present("users", ["id","name","email"])
Support for pam
.INDENT 0.0
.TP
+.B salt.modules.pam.__virtual__()
+Set the virtual name for the module
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.pam.read_file(file_name)
This is just a test function, to make sure parsing works
.sp
@@ -195590,9 +205012,26 @@ see the \fI\%Parallels Desktop Reference Guide\fP\&.
What has not been implemented yet can be accessed through \fBparallels.prlctl\fP
and \fBparallels.prlsrvctl\fP (note the preceding double dash \fB\-\-\fP as
necessary):
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+salt \(aq*\(aq parallels.prlctl installtools macvm runas=macdev
+salt \-\- \(aq*\(aq parallels.prlctl capture \(aqmacvm \-\-file macvm.display.png\(aq runas=macdev
+salt \-\- \(aq*\(aq parallels.prlsrvctl set \(aq\-\-mem\-limit auto\(aq runas=macdev
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
.sp
New in version 2016.3.0.
+.INDENT 0.0
+.TP
+.B salt.modules.parallels.__virtual__()
+Load this module if prlctl is available
+.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.parallels.clone(name, new_name, linked=False, template=False, runas=None)
@@ -196225,6 +205664,12 @@ has been written to utilize sfdisk instead. For further information, please
reference the man page for \fBsfdisk(8)\fP\&.
.INDENT 0.0
.TP
+.B salt.modules.parted.__virtual__()
+Only work on POSIX\-like systems, which have parted and lsblk installed.
+These are usually provided by the \fBparted\fP and \fButil\-linux\fP packages.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.parted.align_check(device, part_type, partition)
Check if partition satisfies the alignment constraint of part_type.
Type must be "minimal" or "optimal".
@@ -196654,6 +206099,11 @@ pcs
.sp
New in version 2016.3.0.
+.INDENT 0.0
+.TP
+.B salt.modules.pcs.__virtual__()
+Only load if pcs package is installed
+.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.pcs.auth(nodes, pcsuser=\(aqhacluster\(aq, pcspasswd=\(aqhacluster\(aq, extra_args=None)
@@ -196679,10 +206129,7 @@ CLI Example:
.sp
.nf
.ft C
-salt \(aq*\(aq pcs.auth nodes=\(aq[ node1.example.org node2.example.org ]\(aq \e
- pcsuser=\(aqhacluster\(aq \e
- pcspasswd=\(aqhoonetorg\(aq \e
- extra_args=[ \(aq\-\-force\(aq ]
+salt \(aq*\(aq pcs.auth nodes=\(aq[ node1.example.org node2.example.org ]\(aq pcsuser=hacluster pcspasswd=hoonetorg extra_args="[ \(aq\-\-force\(aq ]"
.ft P
.fi
.UNINDENT
@@ -196710,8 +206157,7 @@ CLI Example:
.sp
.nf
.ft C
-salt \(aq*\(aq pcs.cib_create cibfile=\(aq/tmp/VIP_apache_1.cib\(aq \e
- \(aqscope=False\(aq
+salt \(aq*\(aq pcs.cib_create cibfile=\(aq/tmp/VIP_apache_1.cib\(aq scope=False
.ft P
.fi
.UNINDENT
@@ -196739,8 +206185,7 @@ CLI Example:
.sp
.nf
.ft C
-salt \(aq*\(aq pcs.cib_push cibfile=\(aq/tmp/VIP_apache_1.cib\(aq \e
- \(aqscope=False\(aq
+salt \(aq*\(aq pcs.cib_push cibfile=\(aq/tmp/VIP_apache_1.cib\(aq scope=False
.ft P
.fi
.UNINDENT
@@ -196765,7 +206210,7 @@ CLI Example:
.sp
.nf
.ft C
-salt \(aq*\(aq pcs.cluster_node_add node=node2.example.org\(aq
+salt \(aq*\(aq pcs.cluster_node_add node=node2.example.org
.ft P
.fi
.UNINDENT
@@ -196793,8 +206238,7 @@ CLI Example:
.sp
.nf
.ft C
-salt \(aq*\(aq pcs.cluster_setup nodes=\(aq[ node1.example.org node2.example.org ]\(aq \e
- pcsclustername=\(aqpcscluster\(aq
+salt \(aq*\(aq pcs.cluster_setup nodes=\(aq[ node1.example.org node2.example.org ]\(aq pcsclustername=pcscluster
.ft P
.fi
.UNINDENT
@@ -196921,9 +206365,7 @@ CLI Example:
.sp
.nf
.ft C
-salt \(aq*\(aq pcs.prop_set prop=\(aqno\-quorum\-policy\(aq \e
- value=\(aqignore\(aq \e
- cibfile=\(aq/tmp/2_node_cluster.cib\(aq
+salt \(aq*\(aq pcs.prop_set prop=\(aqno\-quorum\-policy\(aq value=\(aqignore\(aq cibfile=\(aq/tmp/2_node_cluster.cib\(aq
.ft P
.fi
.UNINDENT
@@ -196951,9 +206393,7 @@ CLI Example:
.sp
.nf
.ft C
-salt \(aq*\(aq pcs.prop_show cibfile=\(aq/tmp/2_node_cluster.cib\(aq \e
- prop=\(aqno\-quorum\-policy\(aq \e
- cibfile=\(aq/tmp/2_node_cluster.cib\(aq
+salt \(aq*\(aq pcs.prop_show cibfile=\(aq/tmp/2_node_cluster.cib\(aq prop=\(aqno\-quorum\-policy\(aq cibfile=\(aq/tmp/2_node_cluster.cib\(aq
.ft P
.fi
.UNINDENT
@@ -196984,13 +206424,7 @@ CLI Example:
.sp
.nf
.ft C
-salt \(aq*\(aq pcs.resource_create resource_id=\(aqgalera\(aq \e
- resource_type=\(aqocf:heartbeat:galera\(aq \e
- resource_options="[ \e
- \(aqwsrep_cluster_address=gcomm://node1.example.org,node2.example.org,node3.example.org\(aq \e
- \(aq\-\-master\(aq \e
- ]" \e
- cibfile=\(aq/tmp/cib_for_galera.cib\(aq
+salt \(aq*\(aq pcs.resource_create resource_id=\(aqgalera\(aq resource_type=\(aqocf:heartbeat:galera\(aq resource_options="[\(aqwsrep_cluster_address=gcomm://node1.example.org,node2.example.org,node3.example.org\(aq, \(aq\-\-master\(aq]" cibfile=\(aq/tmp/cib_for_galera.cib\(aq
.ft P
.fi
.UNINDENT
@@ -197018,8 +206452,7 @@ CLI Example:
.sp
.nf
.ft C
-salt \(aq*\(aq pcs.resource_show resource_id=\(aqgalera\(aq \e
- cibfile=\(aq/tmp/cib_for_galera.cib\(aq
+salt \(aq*\(aq pcs.resource_show resource_id=\(aqgalera\(aq cibfile=\(aq/tmp/cib_for_galera.cib\(aq
.ft P
.fi
.UNINDENT
@@ -197050,19 +206483,8 @@ CLI Example:
.sp
.nf
.ft C
-salt \(aq*\(aq pcs.stonith_create stonith_id=\(aqeps_fence\(aq \e
- stonith_device_type=\(aqfence_eps\(aq \e
- stonith_device_options="[ \e
- \(aqpcmk_host_map=node1.example.org:01;node2.example.org:02\(aq, \e
- \(aqipaddr=myepsdevice.example.org\(aq, \e
- \(aqaction=reboot\(aq, \e
- \(aqpower_wait=5\(aq, \e
- \(aqverbose=1\(aq, \e
- \(aqdebug=/var/log/pcsd/eps_fence.log\(aq, \e
- \(aqlogin=hidden\(aq, \e
- \(aqpasswd=hoonetorg\(aq \e
- ]" \e
- cibfile=\(aq/tmp/cib_for_stonith.cib\(aq
+salt \(aq*\(aq pcs.stonith_create stonith_id=\(aqeps_fence\(aq stonith_device_type=\(aqfence_eps\(aq
+ stonith_device_options="[\(aqpcmk_host_map=node1.example.org:01;node2.example.org:02\(aq, \(aqipaddr=myepsdevice.example.org\(aq, \(aqaction=reboot\(aq, \(aqpower_wait=5\(aq, \(aqverbose=1\(aq, \(aqdebug=/var/log/pcsd/eps_fence.log\(aq, \(aqlogin=hidden\(aq, \(aqpasswd=hoonetorg\(aq]" cibfile=\(aq/tmp/cib_for_stonith.cib\(aq
.ft P
.fi
.UNINDENT
@@ -197090,8 +206512,7 @@ CLI Example:
.sp
.nf
.ft C
-salt \(aq*\(aq pcs.stonith_show stonith_id=\(aqeps_fence\(aq \e
- cibfile=\(aq/tmp/2_node_cluster.cib\(aq
+salt \(aq*\(aq pcs.stonith_show stonith_id=\(aqeps_fence\(aq cibfile=\(aq/tmp/2_node_cluster.cib\(aq
.ft P
.fi
.UNINDENT
@@ -197114,6 +206535,11 @@ posix
.sp
New in version 2017.7.0.
+.INDENT 0.0
+.TP
+.B salt.modules.pdbedit.__virtual__()
+Provides pdbedit if available
+.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.pdbedit.create(login, password, password_hashed=False, machine_account=False)
@@ -197448,6 +206874,11 @@ Philips HUE lamps module for proxy.
.sp
New in version 2015.8.3.
+.INDENT 0.0
+.TP
+.B salt.modules.philips_hue.__virtual__()
+Start the Philips HUE only for proxies.
+.UNINDENT
.SS salt.modules.pillar
.sp
Extract the pillar data for this minion
@@ -197525,10 +206956,9 @@ salt \(aq*\(aq pillar.ext "{\(aqgit\(aq: [{\(aqmybranch https://github.com/myuse
New in version 0.14.
.sp
-Attempt to retrieve the named value from pillar, if the named value is not
-available return the passed default. The default return is an empty string
-except \fB__opts__[\(aqpillar_raise_on_missing\(aq]\fP is set to True, in which
-case a \fBKeyError\fP exception will be raised.
+Attempt to retrieve the named value from in\-memory pillar data\&. If the pillar key is not present in the in\-memory
+pillar, then the value specified in the \fBdefault\fP option (described
+below) will be returned.
.sp
If the merge parameter is set to \fBTrue\fP, the default will be recursively
merged into the returned pillar data.
@@ -197564,8 +206994,12 @@ pkg:apache
The pillar key to get value from
.TP
.B default
-If specified, return this value in case when named pillar value does
-not exist.
+The value specified by this option will be returned if the desired
+pillar key does not exist.
+.sp
+If a default value is specified, then it will be an empty string,
+unless \fBpillar_raise_on_missing\fP is set to \fBTrue\fP, in
+which case an error will be raised.
.TP
.B merge
\fBFalse\fP
@@ -197762,10 +207196,9 @@ salt \(aq*\(aq pillar.filter_by \(aq{web: Serve it up, db: I query, default: x_x
New in version 0.14.
.sp
-Attempt to retrieve the named value from pillar, if the named value is not
-available return the passed default. The default return is an empty string
-except \fB__opts__[\(aqpillar_raise_on_missing\(aq]\fP is set to True, in which
-case a \fBKeyError\fP exception will be raised.
+Attempt to retrieve the named value from in\-memory pillar data\&. If the pillar key is not present in the in\-memory
+pillar, then the value specified in the \fBdefault\fP option (described
+below) will be returned.
.sp
If the merge parameter is set to \fBTrue\fP, the default will be recursively
merged into the returned pillar data.
@@ -197801,8 +207234,12 @@ pkg:apache
The pillar key to get value from
.TP
.B default
-If specified, return this value in case when named pillar value does
-not exist.
+The value specified by this option will be returned if the desired
+pillar key does not exist.
+.sp
+If a default value is specified, then it will be an empty string,
+unless \fBpillar_raise_on_missing\fP is set to \fBTrue\fP, in
+which case an error will be raised.
.TP
.B merge
\fBFalse\fP
@@ -198229,31 +207666,37 @@ back slash is an escape character.
.UNINDENT
.INDENT 0.0
.TP
+.B salt.modules.pip.__virtual__()
+There is no way to verify that pip is installed without inspecting the
+entire filesystem. If it\(aqs not installed in a conventional location, the
+user is required to provide the location of pip each time it is used.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.pip.freeze(bin_env=None, user=None, cwd=None, use_vt=False, env_vars=None, **kwargs)
Return a list of installed packages either globally or in the specified
virtualenv
.INDENT 7.0
.TP
.B bin_env
-path to pip bin or path to virtualenv. If doing an uninstall from
-the system python and want to use a specific pip bin (pip\-2.7,
-pip\-2.6, etc..) just specify the pip bin you want.
-If uninstalling from a virtualenv, just use the path to the virtualenv
-(/home/code/path/to/virtualenv/)
+Path to pip (or to a virtualenv). This can be used to specify the path
+to the pip to use when more than one Python release is installed (e.g.
+\fB/usr/bin/pip\-2.7\fP or \fB/usr/bin/pip\-2.6\fP\&. If a directory path is
+specified, it is assumed to be a virtualenv.
.TP
.B user
The user under which to run pip
.TP
.B cwd
-Current working directory to run pip from
+Directory from which to run pip
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 7.0
.INDENT 3.5
If the version of pip available is older than 8.0.3, the list will not
-include the packages pip, wheel, setuptools, or distribute even if they
-are installed.
+include the packages \fBpip\fP, \fBwheel\fP, \fBsetuptools\fP, or
+\fBdistribute\fP even if they are installed.
.UNINDENT
.UNINDENT
.sp
@@ -198263,15 +207706,11 @@ CLI Example:
.sp
.nf
.ft C
-salt \(aq*\(aq pip.freeze /home/code/path/to/virtualenv/
+salt \(aq*\(aq pip.freeze bin_env=/home/code/path/to/virtualenv
.ft P
.fi
.UNINDENT
.UNINDENT
-.sp
-Changed in version 2016.11.2: The packages pip, wheel, setuptools, and distribute are included if the
-installed pip is new enough.
-
.UNINDENT
.INDENT 0.0
.TP
@@ -198289,15 +207728,18 @@ Comma separated list of packages to install
Path to requirements
.TP
.B bin_env
-Path to pip bin or path to virtualenv. If doing a system install,
-and want to use a specific pip bin (pip\-2.7, pip\-2.6, etc..) just
-specify the pip bin you want.
+Path to pip (or to a virtualenv). This can be used to specify the path
+to the pip to use when more than one Python release is installed (e.g.
+\fB/usr/bin/pip\-2.7\fP or \fB/usr/bin/pip\-2.6\fP\&. If a directory path is
+specified, it is assumed to be a virtualenv.
.sp
\fBNOTE:\fP
.INDENT 7.0
.INDENT 3.5
-If installing into a virtualenv, just use the path to the
-virtualenv (e.g. \fB/home/code/path/to/virtualenv/\fP)
+For Windows, if the pip module is being used to upgrade the pip
+package, bin_env should be the path to the virtualenv or to the
+python binary that should be used. The pip command is unable to
+upgrade itself in Windows.
.UNINDENT
.UNINDENT
.TP
@@ -198405,7 +207847,7 @@ install command.
The user under which to run pip
.TP
.B cwd
-Current working directory to run pip from
+Directory from which to run pip
.TP
.B pre_releases
Include pre\-releases in the available versions
@@ -198493,10 +207935,9 @@ Filter list of installed apps from \fBfreeze\fP and check to see if
.INDENT 7.0
.INDENT 3.5
If the version of pip available is older than 8.0.3, the packages
-wheel, setuptools, and distribute will not be reported by this function
-even if they are installed. Unlike
-\fI\%pip.freeze\fP, this function always
-reports the version of pip which is installed.
+\fBwheel\fP, \fBsetuptools\fP, and \fBdistribute\fP will not be reported by
+this function even if they are installed. Unlike \fI\%pip.freeze\fP, this function always reports the version of
+pip which is installed.
.UNINDENT
.UNINDENT
.sp
@@ -198511,10 +207952,6 @@ salt \(aq*\(aq pip.list salt
.fi
.UNINDENT
.UNINDENT
-.sp
-Changed in version 2016.11.2: The packages wheel, setuptools, and distribute are included if the
-installed pip is new enough.
-
.UNINDENT
.INDENT 0.0
.TP
@@ -198529,9 +207966,10 @@ List all available versions of a pip package
The package to check
.TP
.B bin_env
-Path to pip bin or path to virtualenv. If doing a system install,
-and want to use a specific pip bin (pip\-2.7, pip\-2.6, etc..) just
-specify the pip bin you want.
+Path to pip (or to a virtualenv). This can be used to specify the path
+to the pip to use when more than one Python release is installed (e.g.
+\fB/usr/bin/pip\-2.7\fP or \fB/usr/bin/pip\-2.6\fP\&. If a directory path is
+specified, it is assumed to be a virtualenv.
.TP
.B include_alpha
Include alpha versions in the list
@@ -198546,7 +207984,7 @@ Include release candidates versions in the list
The user under which to run pip
.TP
.B cwd
-Current working directory to run pip from
+Directory from which to run pip
.UNINDENT
.sp
CLI Example:
@@ -198581,35 +208019,29 @@ salt \(aq*\(aq pip.list_upgrades
.INDENT 0.0
.TP
.B salt.modules.pip.uninstall(pkgs=None, requirements=None, bin_env=None, log=None, proxy=None, timeout=None, user=None, cwd=None, saltenv=\(aqbase\(aq, use_vt=False)
-Uninstall packages with pip
-.sp
-Uninstall packages individually or from a pip requirements file. Uninstall
-packages globally or from a virtualenv.
+Uninstall packages individually or from a pip requirements file
.INDENT 7.0
.TP
.B pkgs
comma separated list of packages to install
.TP
.B requirements
-path to requirements.
+Path to requirements file
.TP
.B bin_env
-path to pip bin or path to virtualenv. If doing an uninstall from
-the system python and want to use a specific pip bin (pip\-2.7,
-pip\-2.6, etc..) just specify the pip bin you want.
-If uninstalling from a virtualenv, just use the path to the virtualenv
-(/home/code/path/to/virtualenv/)
+Path to pip (or to a virtualenv). This can be used to specify the path
+to the pip to use when more than one Python release is installed (e.g.
+\fB/usr/bin/pip\-2.7\fP or \fB/usr/bin/pip\-2.6\fP\&. If a directory path is
+specified, it is assumed to be a virtualenv.
.TP
.B log
Log file where a complete (maximum verbosity) record will be kept
.TP
.B proxy
-Specify a proxy in the form
-user:passwd@proxy.server:port. Note that the
-user:password@ is optional and required only if you
-are behind an authenticated proxy. If you provide
-user@proxy.server:port then you will be prompted for a
-password.
+Specify a proxy in the format \fBuser:passwd@proxy.server:port\fP\&. Note
+that the \fBuser:password@\fP is optional and required only if you are
+behind an authenticated proxy. If you provide
+\fBuser@proxy.server:port\fP then you will be prompted for a password.
.TP
.B timeout
Set the socket timeout (default 15 seconds)
@@ -198618,7 +208050,7 @@ Set the socket timeout (default 15 seconds)
The user under which to run pip
.TP
.B cwd
-Current working directory to run pip from
+Directory from which to run pip
.TP
.B use_vt
Use VT terminal emulation (see output while installing)
@@ -198902,6 +208334,11 @@ minion, and it is using a different module (or gives an error similar to
.UNINDENT
.INDENT 0.0
.TP
+.B salt.modules.pkgin.__virtual__()
+Set the virtual pkg module if the os is supported by pkgin
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.pkgin.available_version(*names, **kwargs)
This function is an alias of \fBlatest_version\fP\&.
.INDENT 7.0
@@ -199302,6 +208739,14 @@ providers:
.UNINDENT
.INDENT 0.0
.TP
+.B salt.modules.pkgng.__virtual__()
+Load as \(aqpkg\(aq on FreeBSD 10 and greater.
+Load as \(aqpkg\(aq on DragonFly BSD.
+Load as \(aqpkg\(aq on FreeBSD 9 when config option
+\fBproviders:pkg\fP is set to \(aqpkgng\(aq.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.pkgng.audit(jail=None, chroot=None, root=None)
Audits installed packages against known vulnerabilities
.sp
@@ -199729,7 +209174,7 @@ salt \(aq*\(aq pkg.fetch depends=True
.UNINDENT
.INDENT 0.0
.TP
-.B salt.modules.pkgng.install(name=None, fromrepo=None, pkgs=None, sources=None, jail=None, chroot=None, root=None, orphan=False, force=False, glob=False, local=False, dryrun=False, quiet=False, reinstall_requires=False, regex=False, pcre=False, **kwargs)
+.B salt.modules.pkgng.install(name=None, fromrepo=None, pkgs=None, sources=None, jail=None, chroot=None, root=None, orphan=False, force=False, glob=False, local=False, dryrun=False, quiet=False, reinstall_requires=False, regex=False, pcre=False, batch=False, **kwargs)
Install package(s) from a repository
.INDENT 7.0
.TP
@@ -199914,7 +209359,23 @@ CLI Example:
.sp
.nf
.ft C
-salt \(aq*\(aq pkg.install pcre=True
+
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.TP
+.B batch
+Use BATCH=true for pkg install, skipping all questions.
+Be careful when using in production.
+.sp
+CLI Example:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+salt \(aq*\(aq pkg.install batch=True
.ft P
.fi
.UNINDENT
@@ -200992,6 +210453,11 @@ minion, and it is using a different module (or gives an error similar to
.UNINDENT
.INDENT 0.0
.TP
+.B salt.modules.pkgutil.__virtual__()
+Set the virtual pkg module if the os is Solaris
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.pkgutil.install(name=None, refresh=False, version=None, pkgs=None, **kwargs)
Install packages using the pkgutil tool.
.sp
@@ -201272,6 +210738,11 @@ salt \(aq*\(aq pkgutil.version CSWpython
Configure \fBportage(5)\fP
.INDENT 0.0
.TP
+.B salt.modules.portage_config.__virtual__()
+Confirm this module is on a Gentoo based system.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.portage_config.append_to_package_conf(conf, atom=\(aq\(aq, flags=None, string=\(aq\(aq, overwrite=False)
Append a string or a list of flags for a given package or DEPEND atom to a
given configuration file.
@@ -201531,6 +211002,11 @@ changes are made to them. Each file should look as if it has been edited by
hand; order, comments and whitespace are all preserved.
.INDENT 0.0
.TP
+.B salt.modules.postfix.__virtual__()
+Only load the module if Postfix is installed
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.postfix.delete(queue_id)
Delete message(s) from the mail queue
.sp
@@ -201747,6 +211223,12 @@ postgres.bins_dir: \(aq/usr/pgsql\-9.5/bin/\(aq
.UNINDENT
.INDENT 0.0
.TP
+.B salt.modules.postgres.__virtual__()
+Only load this module if the psql bin exist.
+initdb bin might also be used, but its presence will be detected on runtime.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.postgres.available_extensions(user=None, host=None, port=None, maintenance_db=None, password=None, runas=None)
List available postgresql extensions
.sp
@@ -203127,6 +212609,11 @@ salt \(aq*\(aq postgres.version
Support for poudriere
.INDENT 0.0
.TP
+.B salt.modules.poudriere.__virtual__()
+Module load on freebsd only and if poudriere installed
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.poudriere.bulk_build(jail, pkg_file, keep=False)
Run bulk build on poudriere server.
.sp
@@ -203328,6 +212815,12 @@ powerpath support.
Assumes RedHat
.INDENT 0.0
.TP
+.B salt.modules.powerpath.__virtual__()
+Provide this only on Linux systems until proven to
+work elsewhere.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.powerpath.add_license(key)
Add a license
.UNINDENT
@@ -203356,6 +212849,11 @@ salt \(aq*\(aq network.get_http_proxy
.UNINDENT
.INDENT 0.0
.TP
+.B salt.modules.proxy.__virtual__()
+Only work on Mac OS and Windows
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.proxy.get_ftp_proxy(network_service=\(aqEthernet\(aq)
Returns the current ftp proxy settings
.INDENT 7.0
@@ -203486,8 +212984,8 @@ The network service to apply the changes to, this only necessary on
macOS
.TP
.B bypass_hosts
-The hosts that are allowed to by pass the proxy. Only used on Windows for other OS\(aqs use
-set_proxy_bypass to edit the bypass hosts.
+The hosts that are allowed to by pass the proxy. Only used on Windows
+for other OS\(aqs use set_proxy_bypass to edit the bypass hosts.
.UNINDENT
.sp
CLI Example:
@@ -203505,8 +213003,9 @@ salt \(aq*\(aq proxy.set_ftp_proxy example.com 1080 user=proxy_user password=pro
.INDENT 0.0
.TP
.B salt.modules.proxy.set_http_proxy(server, port, user=None, password=None, network_service=\(aqEthernet\(aq, bypass_hosts=None)
-Sets the http proxy settings. Note: On Windows this will override any other proxy settings you have,
-the preferred method of updating proxies on windows is using set_proxy.
+Sets the http proxy settings. Note: On Windows this will override any other
+proxy settings you have, the preferred method of updating proxies on windows
+is using set_proxy.
.INDENT 7.0
.TP
.B server
@@ -203526,8 +213025,8 @@ The network service to apply the changes to, this only necessary on
macOS
.TP
.B bypass_hosts
-The hosts that are allowed to by pass the proxy. Only used on Windows for other OS\(aqs use
-set_proxy_bypass to edit the bypass hosts.
+The hosts that are allowed to by pass the proxy. Only used on Windows
+for other OS\(aqs use set_proxy_bypass to edit the bypass hosts.
.UNINDENT
.sp
CLI Example:
@@ -203545,8 +213044,9 @@ salt \(aq*\(aq proxy.set_http_proxy example.com 1080 user=proxy_user password=pr
.INDENT 0.0
.TP
.B salt.modules.proxy.set_https_proxy(server, port, user=None, password=None, network_service=\(aqEthernet\(aq, bypass_hosts=None)
-Sets the https proxy settings. Note: On Windows this will override any other proxy settings you have,
-the preferred method of updating proxies on windows is using set_proxy.
+Sets the https proxy settings. Note: On Windows this will override any other
+proxy settings you have, the preferred method of updating proxies on windows
+is using set_proxy.
.INDENT 7.0
.TP
.B server
@@ -203566,8 +213066,8 @@ The network service to apply the changes to, this only necessary on
macOS
.TP
.B bypass_hosts
-The hosts that are allowed to by pass the proxy. Only used on Windows for other OS\(aqs use
-set_proxy_bypass to edit the bypass hosts.
+The hosts that are allowed to by pass the proxy. Only used on Windows
+for other OS\(aqs use set_proxy_bypass to edit the bypass hosts.
.UNINDENT
.sp
CLI Example:
@@ -203621,7 +213121,20 @@ The proxy server to use
The password to use if required by the server
.TP
.B types
-The types of proxy connections should be setup with this server. Valid types are http and https.
+The types of proxy connections should be setup with this server. Valid
+types are:
+.INDENT 7.0
+.INDENT 3.5
+.INDENT 0.0
+.IP \(bu 2
+\fBhttp\fP
+.IP \(bu 2
+\fBhttps\fP
+.IP \(bu 2
+\fBftp\fP
+.UNINDENT
+.UNINDENT
+.UNINDENT
.TP
.B bypass_hosts
The hosts that are allowed to by pass the proxy.
@@ -204390,6 +213903,11 @@ salt publish.runner manage.down
Execute puppet routines
.INDENT 0.0
.TP
+.B salt.modules.puppet.__virtual__()
+Only load if puppet is installed
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.puppet.disable(message=None)
New in version 2014.7.0.
@@ -204658,6 +214176,16 @@ pushover:
.UNINDENT
.INDENT 0.0
.TP
+.B salt.modules.pushover_notify.__virtual__()
+Return virtual name of the module.
+.INDENT 7.0
+.TP
+.B Returns
+The virtual name of the module.
+.UNINDENT
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.pushover_notify.post_message(user=None, device=None, message=None, title=None, priority=None, expire=None, retry=None, sound=None, api_version=1, token=None)
Send a message to a Pushover user or group.
.INDENT 7.0
@@ -204716,6 +214244,11 @@ minion, and it is using a different module (or gives an error similar to
.UNINDENT
.INDENT 0.0
.TP
+.B salt.modules.pw_group.__virtual__()
+Set the user module if the kernel is FreeBSD or Dragonfly
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.pw_group.add(name, gid=None, **kwargs)
Add the specified group
.sp
@@ -204873,6 +214406,11 @@ minion, and it is using a different module (or gives an error similar to
.UNINDENT
.INDENT 0.0
.TP
+.B salt.modules.pw_user.__virtual__()
+Set the user module if the kernel is FreeBSD or DragonFly
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.pw_user.add(name, uid=None, gid=None, groups=None, home=None, shell=None, unique=True, fullname=\(aq\(aq, roomnumber=\(aq\(aq, workphone=\(aq\(aq, homephone=\(aq\(aq, createhome=True, loginclass=None, **kwargs)
Add a user to the minion
.sp
@@ -205446,6 +214984,11 @@ qemu\-img
.UNINDENT
.INDENT 0.0
.TP
+.B salt.modules.qemu_img.__virtual__()
+Only load if qemu\-img is installed
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.qemu_img.convert(orig, dest, fmt)
Convert an existing disk image to another format using qemu\-img
.sp
@@ -205488,6 +215031,11 @@ The qemu system comes with powerful tools, such as qemu\-img and qemu\-nbd which
are used here to build up kvm images.
.INDENT 0.0
.TP
+.B salt.modules.qemu_nbd.__virtual__()
+Only load if qemu\-img and qemu\-nbd are installed
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.qemu_nbd.clear(mnt)
Pass in the mnt dict returned from nbd_mount to unmount and disconnect
the image from nbd. If all of the partitions are unmounted return an
@@ -205563,6 +215111,11 @@ salt \(aq*\(aq qemu_nbd.mount /dev/nbd0
Module for managing quotas on POSIX\-like systems.
.INDENT 0.0
.TP
+.B salt.modules.quota.__virtual__()
+Only work on POSIX\-like systems with setquota binary available
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.quota.get_mode(device)
Report whether the quota system for this device is on or off
.sp
@@ -205689,6 +215242,11 @@ Todo: A lot, need to add cluster support, logging, and minion configuration
data.
.INDENT 0.0
.TP
+.B salt.modules.rabbitmq.__virtual__()
+Verify RabbitMQ is installed.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.rabbitmq.add_user(name, password=None, runas=None)
Add a rabbitMQ user via rabbitmqctl user_add
.sp
@@ -205805,7 +215363,7 @@ CLI Example:
.sp
.nf
.ft C
-salt \(aq*\(aq rabbitmq.delete_policy / HA\(aq
+salt \(aq*\(aq rabbitmq.delete_policy / HA
.ft P
.fi
.UNINDENT
@@ -205907,7 +215465,7 @@ CLI Example:
.sp
.nf
.ft C
-salt \(aq*\(aq rabbitmq.join_cluster \(aqrabbit.example.com\(aq \(aqrabbit\(aq
+salt \(aq*\(aq rabbitmq.join_cluster rabbit.example.com rabbit
.ft P
.fi
.UNINDENT
@@ -205958,7 +215516,7 @@ CLI Example:
.sp
.nf
.ft C
-salt \(aq*\(aq rabbitmq.list_permissions \(aq/myvhost\(aq
+salt \(aq*\(aq rabbitmq.list_permissions /myvhost
.ft P
.fi
.UNINDENT
@@ -205978,7 +215536,7 @@ CLI Example:
.sp
.nf
.ft C
-salt \(aq*\(aq rabbitmq.list_policies\(aq
+salt \(aq*\(aq rabbitmq.list_policies
.ft P
.fi
.UNINDENT
@@ -206031,7 +215589,7 @@ CLI Example:
.sp
.nf
.ft C
-salt \(aq*\(aq rabbitmq.list_user_permissions \(aquser\(aq.
+salt \(aq*\(aq rabbitmq.list_user_permissions user
.ft P
.fi
.UNINDENT
@@ -206135,7 +215693,7 @@ CLI Example:
.sp
.nf
.ft C
-salt \(aq*\(aq rabbitmq.set_permissions \(aqmyvhost\(aq \(aqmyuser\(aq
+salt \(aq*\(aq rabbitmq.set_permissions myvhost myuser
.ft P
.fi
.UNINDENT
@@ -206171,7 +215729,7 @@ CLI Example:
.sp
.nf
.ft C
-salt \(aq*\(aq rabbitmq.set_user_tags \(aqmyadmin\(aq \(aqadministrator\(aq
+salt \(aq*\(aq rabbitmq.set_user_tags myadmin administrator
.ft P
.fi
.UNINDENT
@@ -206414,6 +215972,11 @@ New in version 2015.8.0.
Requires a \fBusername\fP and a \fBpassword\fP in \fB/etc/salt/minion\fP:
.INDENT 0.0
.TP
+.B salt.modules.rallydev.__virtual__()
+Only load the module if apache is installed
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.rallydev.list_items(name)
List items of a particular type
.sp
@@ -206602,6 +216165,16 @@ random_org:
.UNINDENT
.INDENT 0.0
.TP
+.B salt.modules.random_org.__virtual__()
+Return virtual name of the module.
+.INDENT 7.0
+.TP
+.B Returns
+The virtual name of the module.
+.UNINDENT
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.random_org.generateBlobs(api_key=None, api_version=None, **kwargs)
List all Slack users.
.INDENT 7.0
@@ -206901,6 +216474,11 @@ salt \(aq*\(aq random_org.getUsage api_key=peWcBiMOS9HrZG15peWcBiMOS9HrZG15 api_
Module for Solaris\(aq Role\-Based Access Control
.INDENT 0.0
.TP
+.B salt.modules.rbac_solaris.__virtual__()
+Provides rbac if we are running on a solaris like system
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.rbac_solaris.auth_add(user, auth)
Add authorization to user
.INDENT 7.0
@@ -207213,6 +216791,11 @@ good alternatives to work with multiple versions of Ruby on the same box.
.sp
New in version 0.16.0.
+.INDENT 0.0
+.TP
+.B salt.modules.rbenv.__virtual__()
+Only work on POSIX\-like systems
+.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.rbenv.default(ruby=None, runas=None)
@@ -207467,6 +217050,11 @@ salt \(aq*\(aq rbenv.versions
Manage RDP Service on Windows servers
.INDENT 0.0
.TP
+.B salt.modules.rdp.__virtual__()
+Only works on Windows systems
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.rdp.disable()
Disable RDP the service on the server
.sp
@@ -207661,6 +217249,11 @@ redis.password: None
.UNINDENT
.INDENT 0.0
.TP
+.B salt.modules.redismod.__virtual__()
+Only load this module if redis python module is installed
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.redismod.bgrewriteaof(host=None, port=None, db=None, password=None)
Asynchronously rewrite the append\-only file
.sp
@@ -208443,6 +218036,11 @@ Delay usage until this module is used
.UNINDENT
.INDENT 0.0
.TP
+.B salt.modules.reg.__virtual__()
+Only works on Windows systems with the PyWin32
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.reg.broadcast_change()
Refresh the windows environment.
.sp
@@ -208800,11 +218398,9 @@ under the key. If not passed, the key (Default) value will be set.
.IP \(bu 2
\fBvdata\fP (\fI\%object\fP) \-\-
.sp
-The value data to be set.
-What the type of this parameter
-should be is determined by the value of the vtype
-parameter. The correspondence
-is as follows:
+The value data to be set. Which type this parameter
+should be is determined by the value of the vtype parameter. The
+correspondence is as follows:
.INDENT 2.0
.TP
.B REG_BINARY
@@ -208923,6 +218519,11 @@ vtype=REG_LIST vdata=\(aq[a,b,c]\(aq
Package support for the REST example
.INDENT 0.0
.TP
+.B salt.modules.rest_package.__virtual__()
+Only work on systems that are a proxy minion
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.rest_package.version(*names, **kwargs)
Returns a string representing the package version or an empty string if not
installed. If more than one package name is specified, a dict of
@@ -208983,6 +218584,11 @@ salt \(aqrest\-sample\-proxy\(aq rest_sample.get_test_string
Provide the service module for the proxy\-minion REST sample
.INDENT 0.0
.TP
+.B salt.modules.rest_service.__virtual__()
+Only work on systems that are a proxy minion
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.rest_service.enabled(name, sig=None)
Only the \(aqredbull\(aq service is \(aqenabled\(aq in the test
.sp
@@ -209131,6 +218737,11 @@ Jiri Kotlin <\fI\%jiri.kotlin@ultimum.io\fP>
.UNINDENT
.INDENT 0.0
.TP
+.B salt.modules.restartcheck.__virtual__()
+Only run this module if the psutil python module is installed (package python\-psutil).
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.restartcheck.restartcheck(ignorelist=None, blacklist=None, excludepid=None, verbose=True)
Analyzes files openeded by running processes and seeks for packages which need to be restarted.
.INDENT 7.0
@@ -209240,6 +218851,11 @@ salt \(aq*\(aq ret.get_minions mysql
The networking module for RHEL/Fedora based distros
.INDENT 0.0
.TP
+.B salt.modules.rh_ip.__virtual__()
+Confine this module to RHEL/Fedora based distros
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.rh_ip.apply_network_settings(**settings)
Apply global network configuration.
.sp
@@ -209440,6 +219056,12 @@ minion, and it is using a different module (or gives an error similar to
.UNINDENT
.INDENT 0.0
.TP
+.B salt.modules.rh_service.__virtual__()
+Only work on select distros which still use Red Hat\(aqs /usr/bin/service for
+management of either sysvinit or a hybrid sysvinit/upstart init system.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.rh_service.available(name, limit=\(aq\(aq)
Return True if the named service is available. Use the \fBlimit\fP param to
restrict results to services of that type.
@@ -209718,6 +219340,11 @@ salt \(aq*\(aq service.stop
Riak Salt Module
.INDENT 0.0
.TP
+.B salt.modules.riak.__virtual__()
+Only available on systems with Riak installed.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.riak.cluster_commit()
Commit Cluster Changes
.sp
@@ -209924,6 +219551,11 @@ salt \(aq*\(aq riak.test
Support for rpm
.INDENT 0.0
.TP
+.B salt.modules.rpm.__virtual__()
+Confine this module to rpm based systems
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.rpm.bin_pkg_info(path, saltenv=\(aqbase\(aq)
New in version 2015.8.0.
@@ -210232,6 +219864,11 @@ environments. This also provides a function to generate yum repositories
This module implements the pkgbuild interface
.INDENT 0.0
.TP
+.B salt.modules.rpmbuild.__virtual__()
+Confirm this module is on a RPM based system, and has required utilities
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.rpmbuild.build(runas, tgt, dest_dir, spec, sources, deps, env, template, saltenv=\(aqbase\(aq, log_dir=\(aq/var/log/salt/pkgbuild\(aq)
Given the package destination directory, the spec file source and package
sources, use mock to safely build the rpm defined in the spec file
@@ -210431,6 +220068,11 @@ This data can also be passed into pillar\&.
Options passed into opts will overwrite options passed into pillar.
.INDENT 0.0
.TP
+.B salt.modules.rsync.__virtual__()
+Only load module if rsync binary is present
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.rsync.config(conf_path=\(aq/etc/rsyncd.conf\(aq)
Changed in version 2016.3.0: Return data now contains just the contents of the rsyncd.conf as a
string, instead of a dictionary as returned from \fBcmd.run_all\fP\&.
@@ -210559,6 +220201,12 @@ alternative(s), such as chrony and openntpd both aliased to ntpd.
.UNINDENT
.INDENT 0.0
.TP
+.B salt.modules.runit.__virtual__()
+Virtual service only on systems using runit as init process (PID 1).
+Otherwise, use this module with the provider mechanism.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.runit.add_svc_avail_path(path)
Add a path that may contain available services.
Return \fBTrue\fP if added (or already present), \fBFalse\fP on error.
@@ -210650,14 +220298,8 @@ Returns \fBTrue\fP if operation is successful
the service\(aqs name
.TP
.B start
-.INDENT 7.0
-.TP
-.B \fBFalse\fP
-Do not start the service once enabled. Default mode.
-(consistent with other service management)
-.UNINDENT
-.sp
-\fBTrue\fP : also start the service at the same time (default sv mode)
+False
+If \fBTrue\fP, start the service once enabled.
.UNINDENT
.sp
CLI Example:
@@ -211559,6 +221201,11 @@ requests
.UNINDENT
.INDENT 0.0
.TP
+.B salt.modules.s3.__virtual__()
+Should work on any modern Python installation
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.s3.delete(bucket, path=None, action=None, key=None, keyid=None, service_url=None, verify_ssl=None, kms_keyid=None, location=None, role_arn=None, path_style=None, https_enable=None)
Delete a bucket, or delete an object from a bucket.
.sp
@@ -211748,11 +221395,7 @@ Note that the \fBenabled\fP argument is not available with this provider.
.INDENT 0.0
.TP
.B codeauthor
-
-.nf
-:email:\(gaMarek Skrobacki \(ga
-.fi
-
+Marek Skrobacki <\fI\%skrobul@skrobul.com\fP>
.UNINDENT
.INDENT 0.0
.TP
@@ -211996,6 +221639,11 @@ salt deviceminion salt_proxy.is_running p8000
Control a salt cloud system
.INDENT 0.0
.TP
+.B salt.modules.saltcloudmod.__virtual__()
+Only load if salt cloud is installed
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.saltcloudmod.create(name, profile)
Create the named vm
.sp
@@ -213895,6 +223543,12 @@ proper packages are installed.
.UNINDENT
.INDENT 0.0
.TP
+.B salt.modules.selinux.__virtual__()
+Check if the os is Linux, and then if selinux is running in permissive or
+enforcing mode.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.selinux.fcontext_add_or_delete_policy(action, name, filetype=None, sel_type=None, sel_user=None, sel_level=None)
New in version 2017.7.0.
@@ -214324,6 +223978,11 @@ sensehat:
.UNINDENT
.INDENT 0.0
.TP
+.B salt.modules.sensehat.__virtual__()
+Only load the module if SenseHat is available
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.sensehat.clear(color=None)
Sets the LED matrix to a single color or turns all LEDs off.
.sp
@@ -214606,6 +224265,16 @@ Given the above, the chip is \(aqcoretemp\-isa\-0000\(aq.
.sp
New in version 2014.7.0.
+.INDENT 0.0
+.TP
+.B salt.modules.serverdensity_device.__virtual__()
+Return virtual name of the module.
+.INDENT 7.0
+.TP
+.B Returns
+The virtual name of the module.
+.UNINDENT
+.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.serverdensity_device.create(name, **params)
@@ -214721,276 +224390,6 @@ salt \(aq*\(aq serverdensity_device.update 51f7eafcdba4bb235e000ae4 name=better_
.UNINDENT
.UNINDENT
.UNINDENT
-.SS salt.modules.service
-.sp
-\fBservice\fP is a virtual module that is fulfilled by one of the following
-modules:
-.TS
-center;
-|l|l|.
-_
-T{
-Execution Module
-T} T{
-Used for
-T}
-_
-T{
-\fBdebian_service\fP
-T} T{
-Debian Wheezy and earlier
-T}
-_
-T{
-\fBfreebsdservice\fP
-T} T{
-FreeBSD\-based OSes using \fBservice(8)\fP
-T}
-_
-T{
-\fBgentoo_service\fP
-T} T{
-Gentoo Linux using \fBsysvinit\fP and
-\fBrc\-update(8)\fP
-T}
-_
-T{
-\fBlaunchctl\fP
-T} T{
-Mac OS hosts using \fBlaunchctl(1)\fP
-T}
-_
-T{
-\fBnetbsdservice\fP
-T} T{
-NetBSD\-based OSes
-T}
-_
-T{
-\fBopenbsdservice\fP
-T} T{
-OpenBSD\-based OSes
-T}
-_
-T{
-\fBrh_service\fP
-T} T{
-RedHat\-based distros and derivatives
-using \fBservice(8)\fP and
-\fBchkconfig(8)\fP\&. Supports both pure
-sysvinit and mixed sysvinit/upstart
-systems.
-T}
-_
-T{
-\fI\%service\fP
-T} T{
-Fallback which simply wraps sysvinit
-scripts
-T}
-_
-T{
-\fBsmf\fP
-T} T{
-Solaris\-based OSes which use SMF
-T}
-_
-T{
-\fBsystemd\fP
-T} T{
-Linux distros which use systemd
-T}
-_
-T{
-\fBupstart\fP
-T} T{
-Ubuntu\-based distros using upstart
-T}
-_
-T{
-\fBwin_service\fP
-T} T{
-Windows
-T}
-_
-.TE
-.nf
-
-.fi
-.sp
-.sp
-If Salt\(aqs OS detection does not identify a different virtual service module, the minion will fall back to using this basic module, which simply wraps sysvinit scripts.
-.INDENT 0.0
-.TP
-.B salt.modules.service.available(name)
-Returns \fBTrue\fP if the specified service is available, otherwise returns
-\fBFalse\fP\&.
-.sp
-CLI Example:
-.INDENT 7.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-salt \(aq*\(aq service.available sshd
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.UNINDENT
-.INDENT 0.0
-.TP
-.B salt.modules.service.get_all()
-Return a list of all available services
-.sp
-CLI Example:
-.INDENT 7.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-salt \(aq*\(aq service.get_all
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.UNINDENT
-.INDENT 0.0
-.TP
-.B salt.modules.service.missing(name)
-The inverse of service.available.
-Returns \fBTrue\fP if the specified service is not available, otherwise returns
-\fBFalse\fP\&.
-.sp
-CLI Example:
-.INDENT 7.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-salt \(aq*\(aq service.missing sshd
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.UNINDENT
-.INDENT 0.0
-.TP
-.B salt.modules.service.reload(name)
-Refreshes config files by calling service reload. Does not perform a full
-restart.
-.sp
-CLI Example:
-.INDENT 7.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-salt \(aq*\(aq service.reload
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.UNINDENT
-.INDENT 0.0
-.TP
-.B salt.modules.service.restart(name)
-Restart the specified service
-.sp
-CLI Example:
-.INDENT 7.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-salt \(aq*\(aq service.restart
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.UNINDENT
-.INDENT 0.0
-.TP
-.B salt.modules.service.run(name, action)
-Run the specified service with an action.
-.sp
-New in version 2015.8.1.
-
-.INDENT 7.0
-.TP
-.B name
-Service name.
-.TP
-.B action
-Action name (like start, stop, reload, restart).
-.UNINDENT
-.sp
-CLI Example:
-.INDENT 7.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-salt \(aq*\(aq service.run apache2 reload
-salt \(aq*\(aq service.run postgresql initdb
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.UNINDENT
-.INDENT 0.0
-.TP
-.B salt.modules.service.start(name)
-Start the specified service
-.sp
-CLI Example:
-.INDENT 7.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-salt \(aq*\(aq service.start
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.UNINDENT
-.INDENT 0.0
-.TP
-.B salt.modules.service.status(name, sig=None)
-Return the status for a service, returns the PID or an empty string if the
-service is running or not, pass a signature to use to find the service via
-ps
-.sp
-CLI Example:
-.INDENT 7.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-salt \(aq*\(aq service.status [service signature]
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.UNINDENT
-.INDENT 0.0
-.TP
-.B salt.modules.service.stop(name)
-Stop the specified service
-.sp
-CLI Example:
-.INDENT 7.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-salt \(aq*\(aq service.stop
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.UNINDENT
.SS salt.modules.servicenow module
.sp
Module for execution of ServiceNow CI (configuration items)
@@ -215024,6 +224423,11 @@ servicenow:
.UNINDENT
.INDENT 0.0
.TP
+.B salt.modules.servicenow.__virtual__()
+Only load this module if servicenow is installed on this minion.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.servicenow.delete_record(table, sys_id)
Delete an existing record
.INDENT 7.0
@@ -215138,344 +224542,6 @@ salt myminion servicenow.update_record_field sys_user 2348234 first_name jimmy
.UNINDENT
.UNINDENT
.UNINDENT
-.SS salt.modules.shadow
-.sp
-\fBshadow\fP is a virtual module that is fulfilled by one of the following
-modules:
-.TS
-center;
-|l|l|.
-_
-T{
-Execution Module
-T} T{
-Used for
-T}
-_
-T{
-\fI\%shadow\fP
-T} T{
-Linux
-T}
-_
-T{
-\fBbsd_shadow\fP
-T} T{
-FreeBSD, OpenBSD, NetBSD
-T}
-_
-T{
-\fBsolaris_shadow\fP
-T} T{
-Solaris\-based OSes
-T}
-_
-T{
-\fBwin_shadow\fP
-T} T{
-Windows
-T}
-_
-.TE
-.nf
-
-.fi
-.sp
-.sp
-Manage the shadow file on Linux systems
-.sp
-\fBIMPORTANT:\fP
-.INDENT 0.0
-.INDENT 3.5
-If you feel that Salt should be using this module to manage passwords on a
-minion, and it is using a different module (or gives an error similar to
-\fI\(aqshadow.info\(aq is not available\fP), see here\&.
-.UNINDENT
-.UNINDENT
-.INDENT 0.0
-.TP
-.B salt.modules.shadow.default_hash()
-Returns the default hash used for unset passwords
-.sp
-CLI Example:
-.INDENT 7.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-salt \(aq*\(aq shadow.default_hash
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.UNINDENT
-.INDENT 0.0
-.TP
-.B salt.modules.shadow.del_password(name)
-New in version 2014.7.0.
-
-.sp
-Delete the password from name user
-.sp
-CLI Example:
-.INDENT 7.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-salt \(aq*\(aq shadow.del_password username
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.UNINDENT
-.INDENT 0.0
-.TP
-.B salt.modules.shadow.gen_password(password, crypt_salt=None, algorithm=\(aqsha512\(aq)
-New in version 2014.7.0.
-
-.sp
-Generate hashed password
-.sp
-\fBNOTE:\fP
-.INDENT 7.0
-.INDENT 3.5
-When called this function is called directly via remote\-execution,
-the password argument may be displayed in the system\(aqs process list.
-This may be a security risk on certain systems.
-.UNINDENT
-.UNINDENT
-.INDENT 7.0
-.TP
-.B password
-Plaintext password to be hashed.
-.TP
-.B crypt_salt
-Crpytographic salt. If not given, a random 8\-character salt will be
-generated.
-.TP
-.B algorithm
-The following hash algorithms are supported:
-.INDENT 7.0
-.IP \(bu 2
-md5
-.IP \(bu 2
-blowfish (not in mainline glibc, only available in distros that add it)
-.IP \(bu 2
-sha256
-.IP \(bu 2
-sha512 (default)
-.UNINDENT
-.UNINDENT
-.sp
-CLI Example:
-.INDENT 7.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-salt \(aq*\(aq shadow.gen_password \(aqI_am_password\(aq
-salt \(aq*\(aq shadow.gen_password \(aqI_am_password\(aq crypt_salt=\(aqI_am_salt\(aq algorithm=sha256
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.UNINDENT
-.INDENT 0.0
-.TP
-.B salt.modules.shadow.info(name)
-Return information for the specified user
-.sp
-CLI Example:
-.INDENT 7.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-salt \(aq*\(aq shadow.info root
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.UNINDENT
-.INDENT 0.0
-.TP
-.B salt.modules.shadow.lock_password(name)
-New in version 2016.11.0.
-
-.sp
-Lock the password from name user
-.sp
-CLI Example:
-.INDENT 7.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-salt \(aq*\(aq shadow.lock_password username
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.UNINDENT
-.INDENT 0.0
-.TP
-.B salt.modules.shadow.set_date(name, date)
-Sets the value for the date the password was last changed to days since the
-epoch (January 1, 1970). See man chage.
-.sp
-CLI Example:
-.INDENT 7.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-salt \(aq*\(aq shadow.set_date username 0
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.UNINDENT
-.INDENT 0.0
-.TP
-.B salt.modules.shadow.set_expire(name, expire)
-Changed in version 2014.7.0.
-
-.sp
-Sets the value for the date the account expires as days since the epoch
-(January 1, 1970). Using a value of \-1 will clear expiration. See man
-chage.
-.sp
-CLI Example:
-.INDENT 7.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-salt \(aq*\(aq shadow.set_expire username \-1
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.UNINDENT
-.INDENT 0.0
-.TP
-.B salt.modules.shadow.set_inactdays(name, inactdays)
-Set the number of days of inactivity after a password has expired before
-the account is locked. See man chage.
-.sp
-CLI Example:
-.INDENT 7.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-salt \(aq*\(aq shadow.set_inactdays username 7
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.UNINDENT
-.INDENT 0.0
-.TP
-.B salt.modules.shadow.set_maxdays(name, maxdays)
-Set the maximum number of days during which a password is valid.
-See man chage.
-.sp
-CLI Example:
-.INDENT 7.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-salt \(aq*\(aq shadow.set_maxdays username 90
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.UNINDENT
-.INDENT 0.0
-.TP
-.B salt.modules.shadow.set_mindays(name, mindays)
-Set the minimum number of days between password changes. See man chage.
-.sp
-CLI Example:
-.INDENT 7.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-salt \(aq*\(aq shadow.set_mindays username 7
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.UNINDENT
-.INDENT 0.0
-.TP
-.B salt.modules.shadow.set_password(name, password, use_usermod=False)
-Set the password for a named user. The password must be a properly defined
-hash. The password hash can be generated with this command:
-.sp
-\fBpython \-c "import crypt; print crypt.crypt(\(aqpassword\(aq,
-\(aq\e$6\e$SALTsalt\(aq)"\fP
-.sp
-\fBSALTsalt\fP is the 8\-character crpytographic salt. Valid characters in the
-salt are \fB\&.\fP, \fB/\fP, and any alphanumeric character.
-.sp
-Keep in mind that the $7 represents a sha512 hash, if your OS is using a
-different hashing algorithm this needs to be changed accordingly
-.sp
-CLI Example:
-.INDENT 7.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-salt \(aq*\(aq shadow.set_password root \(aq$1$UYCIxa628.9qXjpQCjM4a..\(aq
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.UNINDENT
-.INDENT 0.0
-.TP
-.B salt.modules.shadow.set_warndays(name, warndays)
-Set the number of days of warning before a password change is required.
-See man chage.
-.sp
-CLI Example:
-.INDENT 7.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-salt \(aq*\(aq shadow.set_warndays username 7
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.UNINDENT
-.INDENT 0.0
-.TP
-.B salt.modules.shadow.unlock_password(name)
-New in version 2016.11.0.
-
-.sp
-Unlock the password from name user
-.sp
-CLI Example:
-.INDENT 7.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-salt \(aq*\(aq shadow.unlock_password username
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.UNINDENT
.SS salt.modules.slack_notify
.sp
Module for sending messages to Slack
@@ -215504,6 +224570,16 @@ slack:
.UNINDENT
.INDENT 0.0
.TP
+.B salt.modules.slack_notify.__virtual__()
+Return virtual name of the module.
+.INDENT 7.0
+.TP
+.B Returns
+The virtual name of the module.
+.UNINDENT
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.slack_notify.call_hook(message, attachment=None, color=\(aqgood\(aq, short=False, identifier=None, channel=None, username=None, icon_emoji=None)
Send message to Slack incoming webhook.
.INDENT 7.0
@@ -215857,6 +224933,11 @@ salt \(aq*\(aq slsutil.update \(aq{foo: Foo}\(aq \(aq{bar: Bar}\(aq
Module for running imgadm command on SmartOS
.INDENT 0.0
.TP
+.B salt.modules.smartos_imgadm.__virtual__()
+Provides imgadm only on SmartOS
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.smartos_imgadm.avail(search=None, verbose=False)
Return a list of available images
.INDENT 7.0
@@ -216076,6 +225157,11 @@ Module for running nictagadm command on SmartOS
\&..versionadded:: 2016.11.0
.INDENT 0.0
.TP
+.B salt.modules.smartos_nictagadm.__virtual__()
+Provides nictagadm on SmartOS
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.smartos_nictagadm.add(name, mac, mtu=1500)
Add a new nictag
.INDENT 7.0
@@ -216242,6 +225328,11 @@ salt \(aq*\(aq nictagadm.vms admin
virst compatibility module for managing VMs on SmartOS
.INDENT 0.0
.TP
+.B salt.modules.smartos_virt.__virtual__()
+Provides virt on SmartOS
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.smartos_virt.get_macs(domain)
Return a list off MAC addresses from the named VM
.sp
@@ -216452,6 +225543,11 @@ salt \(aq*\(aq virt.vm_virt_type
Module for running vmadm command on SmartOS
.INDENT 0.0
.TP
+.B salt.modules.smartos_vmadm.__virtual__()
+Provides vmadm on SmartOS
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.smartos_vmadm.create(from_file=None, **kwargs)
Create a new vm
.INDENT 7.0
@@ -217030,6 +226126,11 @@ Interface to SMBIOS/DMI
.sp
.INDENT 0.0
.TP
+.B salt.modules.smbios.__virtual__()
+Only work when dmidecode is installed.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.smbios.get(string, clean=True)
Get an individual DMI string from SMBIOS info
.INDENT 7.0
@@ -217424,6 +226525,11 @@ minion, and it is using a different module (or gives an error similar to
.UNINDENT
.INDENT 0.0
.TP
+.B salt.modules.smf.__virtual__()
+Only work on systems which default to SMF
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.smf.available(name)
Returns \fBTrue\fP if the specified service is available, otherwise returns
\fBFalse\fP\&.
@@ -217764,6 +226870,11 @@ another\-smtp\-login:
.UNINDENT
.INDENT 0.0
.TP
+.B salt.modules.smtp.__virtual__()
+Only load this module if smtplib is available on this minion.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.smtp.send_msg(recipient, message, subject=\(aqMessage from Salt\(aq, sender=None, server=None, use_ssl=\(aqTrue\(aq, username=None, password=None, profile=None)
Send a message to an SMTP recipient. Designed for use in states.
.sp
@@ -217797,6 +226908,11 @@ solaris,illumos
.sp
New in version 2016.3.0.
+.INDENT 0.0
+.TP
+.B salt.modules.solaris_fmadm.__virtual__()
+Provides fmadm only on Solaris
+.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.solaris_fmadm.acquit(fmri)
@@ -218069,6 +227185,11 @@ minion, and it is using a different module (or gives an error similar to
.UNINDENT
.INDENT 0.0
.TP
+.B salt.modules.solaris_group.__virtual__()
+Set the group module if the kernel is SunOS
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.solaris_group.add(name, gid=None, **kwargs)
Add the specified group
.sp
@@ -218166,6 +227287,11 @@ minion, and it is using a different module (or gives an error similar to
.UNINDENT
.INDENT 0.0
.TP
+.B salt.modules.solaris_shadow.__virtual__()
+Only work on POSIX\-like systems
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.solaris_shadow.default_hash()
Returns the default hash used for unset passwords
.sp
@@ -218350,6 +227476,11 @@ This module is assumes we are using solaris\-like shutdown
.sp
New in version 2016.3.0.
+.INDENT 0.0
+.TP
+.B salt.modules.solaris_system.__virtual__()
+Only supported on Solaris\-like systems
+.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.solaris_system.halt()
@@ -218477,6 +227608,11 @@ minion, and it is using a different module (or gives an error similar to
.UNINDENT
.INDENT 0.0
.TP
+.B salt.modules.solaris_user.__virtual__()
+Set the user module if the kernel is SunOS
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.solaris_user.add(name, uid=None, gid=None, groups=None, home=None, shell=None, unique=True, fullname=\(aq\(aq, roomnumber=\(aq\(aq, workphone=\(aq\(aq, homephone=\(aq\(aq, createhome=True, **kwargs)
Add a user to the minion
.sp
@@ -218746,11 +227882,16 @@ salt \(aq*\(aq user.list_groups foo
.TP
.B salt.modules.solaris_user.list_users()
Return a list of all users
+.sp
CLI Example:
-.. code\-block:: bash
.INDENT 7.0
.INDENT 3.5
+.sp
+.nf
+.ft C
salt \(aq*\(aq user.list_users
+.ft P
+.fi
.UNINDENT
.UNINDENT
.UNINDENT
@@ -218829,6 +227970,11 @@ providers:
.UNINDENT
.INDENT 0.0
.TP
+.B salt.modules.solarisips.__virtual__()
+Set the virtual pkg module if the os is Solaris 11
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.solarisips.available_version(name, **kwargs)
This function is an alias of \fBlatest_version\fP\&.
.INDENT 7.0
@@ -219226,6 +228372,11 @@ minion, and it is using a different module (or gives an error similar to
.UNINDENT
.INDENT 0.0
.TP
+.B salt.modules.solarispkg.__virtual__()
+Set the virtual pkg module if the os is Solaris
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.solarispkg.install(name=None, sources=None, saltenv=\(aqbase\(aq, **kwargs)
Install the passed package. Can install packages from the following
sources:
@@ -219702,6 +228853,14 @@ Get verbose output
.UNINDENT
.INDENT 0.0
.TP
+.B salt.modules.solr.__virtual__()
+PRIVATE METHOD
+Solr needs to be installed to use this.
+.sp
+Return: str/bool
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.solr.abort_import(handler, host=None, core_name=None, verbose=False)
MASTER ONLY
Aborts an existing import command to the specified handler.
@@ -220862,6 +230021,11 @@ splunk:
.UNINDENT
.INDENT 0.0
.TP
+.B salt.modules.splunk.__virtual__()
+Only load this module if splunk is installed on this minion.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.splunk.create_user(email, profile=\(aqsplunk\(aq, **kwargs)
create a splunk user by name/email
.sp
@@ -220958,6 +230122,11 @@ splunk:
.UNINDENT
.INDENT 0.0
.TP
+.B salt.modules.splunk_search.__virtual__()
+Only load this module if splunk is installed on this minion.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.splunk_search.create(name, profile=\(aqsplunk\(aq, **kwargs)
Create a splunk search
.sp
@@ -221625,12 +230794,22 @@ to prevent Salt from publishing private data via Salt Mine or others.
.SS salt.modules.ssh_package module
.sp
Service support for the REST example
+.INDENT 0.0
+.TP
+.B salt.modules.ssh_package.__virtual__()
+Only work on proxy
+.UNINDENT
.SS salt.modules.ssh_service module
.sp
Provide the service module for the proxy\-minion SSH sample
.. versionadded:: 2015.8.2
.INDENT 0.0
.TP
+.B salt.modules.ssh_service.__virtual__()
+Only work on systems that are a proxy minion
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.ssh_service.enabled(name, sig=None)
Only the \(aqredbull\(aq service is \(aqenabled\(aq in the test
.UNINDENT
@@ -222167,8 +231346,18 @@ salt \(aq*\(aq snapper.set_config SYNC_ACL=True
.UNINDENT
.UNINDENT
.sp
-Keys are case insensitive as they will be always uppercased to
-snapper convention. The above example is equivalent to:
+Keys are case insensitive as they will be always uppercased to snapper
+convention. The above example is equivalent to:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+salt \(aq*\(aq snapper.set_config sync_acl=True
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
@@ -222282,6 +231471,11 @@ highdata and won\(aqt hit the fileserver except for \fBsalt://\fP links in the
states themselves.
.INDENT 0.0
.TP
+.B salt.modules.state.__virtual__()
+Set the virtualname
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.state.apply(mods=None, **kwargs)
New in version 2015.5.0.
@@ -222478,6 +231672,33 @@ salt \(aq*\(aq state.apply test localconfig=/path/to/minion.yml
.fi
.UNINDENT
.UNINDENT
+.TP
+.B sync_mods
+If specified, the desired custom module types will be synced prior to
+running the SLS files:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+salt \(aq*\(aq state.apply test sync_mods=states,modules
+salt \(aq*\(aq state.apply test sync_mods=all
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+\fBNOTE:\fP
+.INDENT 7.0
+.INDENT 3.5
+This option is ignored when no SLS files are specified, as a
+highstate automatically syncs all custom
+module types.
+.UNINDENT
+.UNINDENT
+.sp
+New in version 2017.7.8,2018.3.3,Fluorine.
+
.UNINDENT
.UNINDENT
.INDENT 0.0
@@ -223104,7 +232325,7 @@ salt \(aq*\(aq state.single pkg.installed name=vim
.UNINDENT
.INDENT 0.0
.TP
-.B salt.modules.state.sls(mods, test=None, exclude=None, queue=False, **kwargs)
+.B salt.modules.state.sls(mods, test=None, exclude=None, queue=False, sync_mods=None, **kwargs)
Execute the states in one or more SLS files
.INDENT 7.0
.TP
@@ -223222,6 +232443,24 @@ the requisite ordering as well as fully validate the state run.
.sp
New in version 2015.8.4.
+.TP
+.B sync_mods
+If specified, the desired custom module types will be synced prior to
+running the SLS files:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+salt \(aq*\(aq state.sls test sync_mods=states,modules
+salt \(aq*\(aq state.sls test sync_mods=all
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+New in version 2017.7.8,2018.3.3,Fluorine.
+
.UNINDENT
.sp
CLI Example:
@@ -223371,6 +232610,11 @@ Module for returning various status data about a minion.
These data can be useful for compiling into stats later.
.INDENT 0.0
.TP
+.B salt.modules.status.__virtual__()
+Not all functions supported by Windows
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.status.all_status()
Return a composite of all status data and info for this minion.
Warning: There is a LOT here!
@@ -223864,6 +233108,11 @@ statuspage:
.sp
New in version 2017.7.0.
+.INDENT 0.0
+.TP
+.B salt.modules.statuspage.__virtual__()
+Return the execution module virtualname.
+.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.statuspage.create(endpoint=\(aqincidents\(aq, api_url=None, page_id=None, api_key=None, api_version=None, **kwargs)
@@ -223884,13 +233133,6 @@ API version. Can also be specified in the config file.
.TP
.B api_url
Custom API URL in case the user has a StatusPage service running in a custom environment.
-.TP
-.B
-.nf
-**
-.fi
-kwargs
-Other params.
.UNINDENT
.sp
CLI Example:
@@ -224196,6 +233438,11 @@ Support for Stormpath
.sp
New in version 2015.8.0.
+.INDENT 0.0
+.TP
+.B salt.modules.stormpath.__virtual__()
+Only load the module if apache is installed
+.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.stormpath.create_account(directory_id, email, password, givenName, surname, **kwargs)
@@ -224618,6 +233865,11 @@ separate file will allow them to load only on SUSE systems, while still
loading under the \fBapache\fP namespace.
.INDENT 0.0
.TP
+.B salt.modules.suse_apache.__virtual__()
+Only load the module if apache is installed.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.suse_apache.a2dismod(mod)
Runs a2dismod for the given mod.
.sp
@@ -224675,6 +233927,11 @@ salt \(aq*\(aq apache.check_mod_enabled status
Subversion SCM
.INDENT 0.0
.TP
+.B salt.modules.svn.__virtual__()
+Only load if svn is installed
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.svn.add(cwd, targets, user=None, username=None, password=None, *opts)
Add files to be tracked by the Subversion working\-copy checkout
.INDENT 7.0
@@ -225202,6 +234459,12 @@ NOTE: For Rackspace cloud files setting keystone.auth_version = 1 is recommended
.UNINDENT
.INDENT 0.0
.TP
+.B salt.modules.swift.__virtual__()
+Only load this module if swift
+is installed on this minion.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.swift.delete(cont, path=None, profile=None)
Delete a container, or delete an object from a container.
.sp
@@ -225321,6 +234584,11 @@ It measures various system parameters such as
CPU, Memory, File I/O, Threads and Mutex.
.INDENT 0.0
.TP
+.B salt.modules.sysbench.__virtual__()
+loads the module, if only sysbench is installed
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.sysbench.cpu()
Tests for the CPU performance of minions.
.sp
@@ -225435,6 +234703,11 @@ Module for interfacing with SysFS
.sp
New in version 2016.3.0.
+.INDENT 0.0
+.TP
+.B salt.modules.sysfs.__virtual__()
+Only work on Linux
+.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.sysfs.attr(key, value=None)
@@ -226121,6 +235394,11 @@ salt \(aq*\(aq syslog_ng.write_version name="3.6"
The sys module provides information about the available functions on the minion
.INDENT 0.0
.TP
+.B salt.modules.sysmod.__virtual__()
+Return as sys
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.sysmod.argspec(module=\(aq\(aq)
Return the argument specification of functions in Salt execution
modules.
@@ -226861,6 +236139,11 @@ salt \(aq*\(aq sys.state_schema pkg.installed
sysrc module for FreeBSD
.INDENT 0.0
.TP
+.B salt.modules.sysrc.__virtual__()
+Only runs if sysrc exists
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.sysrc.get(**kwargs)
Return system rc configuration variables
.sp
@@ -226927,6 +236210,12 @@ salt \(aq*\(aq sysrc.set name=sshd_flags value="\-p 2222"
Support for reboot, shutdown, etc
.INDENT 0.0
.TP
+.B salt.modules.system.__virtual__()
+Only supported on POSIX\-like systems
+Windows, Solaris, and Mac have their own modules
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.system.get_computer_desc()
Get PRETTY_HOSTNAME value stored in /etc/machine\-info
If this file doesn\(aqt exist or the variable doesn\(aqt exist
@@ -226977,14 +236266,17 @@ Get the system date
.TP
.B Parameters
\fButc_offset\fP (\fI\%str\fP) \-\- The utc offset in 4 digit (+0600) format with an
-.UNINDENT
-.sp
optional sign (+/\-). Will default to None which will use the local
-timezone. To set the time based off of UTC use "\(aq+0000\(aq". Note: if being
-passed through the command line will need to be quoted twice to allow
-negative offsets.
-:return: Returns the system date.
-:rtype: str
+timezone. To set the time based off of UTC use "\(aq+0000\(aq". Note: if
+being passed through the command line will need to be quoted twice to
+allow negative offsets.
+.TP
+.B Returns
+Returns the system date.
+.TP
+.B Return type
+\fI\%str\fP
+.UNINDENT
.sp
CLI Example:
.INDENT 7.0
@@ -227006,14 +236298,17 @@ Get the system date/time.
.TP
.B Parameters
\fButc_offset\fP (\fI\%str\fP) \-\- The utc offset in 4 digit (+0600) format with an
-.UNINDENT
-.sp
optional sign (+/\-). Will default to None which will use the local
-timezone. To set the time based off of UTC use "\(aq+0000\(aq". Note: if being
-passed through the command line will need to be quoted twice to allow
-negative offsets.
-:return: Returns the system time in YYYY\-MM\-DD hh:mm:ss format.
-:rtype: str
+timezone. To set the time based off of UTC use "\(aq+0000\(aq". Note: if
+being passed through the command line will need to be quoted twice to
+allow negative offsets.
+.TP
+.B Returns
+Returns the system time in YYYY\-MM\-DD hh:mm:ss format.
+.TP
+.B Return type
+\fI\%str\fP
+.UNINDENT
.sp
CLI Example:
.INDENT 7.0
@@ -227035,14 +236330,17 @@ Get the system time.
.TP
.B Parameters
\fButc_offset\fP (\fI\%str\fP) \-\- The utc offset in 4 digit (+0600) format with an
-.UNINDENT
-.sp
optional sign (+/\-). Will default to None which will use the local
-timezone. To set the time based off of UTC use "\(aq+0000\(aq". Note: if being
-passed through the command line will need to be quoted twice to allow
-negative offsets.
-:return: Returns the system time in HH:MM:SS AM/PM format.
-:rtype: str
+timezone. To set the time based off of UTC use "\(aq+0000\(aq". Note: if
+being passed through the command line will need to be quoted twice to
+allow negative offsets.
+.TP
+.B Returns
+Returns the system time in HH:MM:SS AM/PM format.
+.TP
+.B Return type
+\fI\%str\fP
+.UNINDENT
.sp
CLI Example:
.INDENT 7.0
@@ -227190,13 +236488,24 @@ Set the Windows system date. Use format for the date.
.INDENT 7.0
.TP
.B Parameters
-\fBnewdate\fP (\fI\%str\fP) \-\- The date to set. Can be any of the following formats
-\- YYYY\-MM\-DD
-\- MM\-DD\-YYYY
-\- MM\-DD\-YY
-\- MM/DD/YYYY
-\- MM/DD/YY
-\- YYYY/MM/DD
+\fBnewdate\fP (\fI\%str\fP) \-\-
+.sp
+The date to set. Can be any of the following formats:
+.INDENT 7.0
+.IP \(bu 2
+YYYY\-MM\-DD
+.IP \(bu 2
+MM\-DD\-YYYY
+.IP \(bu 2
+MM\-DD\-YY
+.IP \(bu 2
+MM/DD/YYYY
+.IP \(bu 2
+MM/DD/YY
+.IP \(bu 2
+YYYY/MM/DD
+.UNINDENT
+
.UNINDENT
.sp
CLI Example:
@@ -227240,15 +236549,18 @@ Updates hardware clock, if present, in addition to software
\fBseconds\fP (\fI\%int\fP) \-\- Seconds digit: 0 \- 59
.IP \(bu 2
\fButc_offset\fP (\fI\%str\fP) \-\- The utc offset in 4 digit (+0600) format with an
-.UNINDENT
-.UNINDENT
-.sp
optional sign (+/\-). Will default to None which will use the local
-timezone. To set the time based off of UTC use "\(aq+0000\(aq". Note: if being
-passed through the command line will need to be quoted twice to allow
-negative offsets.
-:return: True if successful. Otherwise False.
-:rtype: bool
+timezone. To set the time based off of UTC use "\(aq+0000\(aq". Note: if
+being passed through the command line will need to be quoted twice to
+allow negative offsets.
+.UNINDENT
+.TP
+.B Returns
+True if successful. Otherwise False.
+.TP
+.B Return type
+\fI\%bool\fP
+.UNINDENT
.sp
CLI Example:
.INDENT 7.0
@@ -227286,15 +236598,18 @@ Meaning you may have to quote the text twice from the command line.
.IP \(bu 2
\fButc_offset\fP (\fI\%str\fP) \-\- The utc offset in 4 digit (+0600) format with an
-.UNINDENT
-.UNINDENT
-.sp
optional sign (+/\-). Will default to None which will use the local
-timezone. To set the time based off of UTC use "\(aq+0000\(aq". Note: if being
-passed through the command line will need to be quoted twice to allow
-negative offsets.
-:return: Returns True if successful. Otherwise False.
-:rtype: bool
+timezone. To set the time based off of UTC use "\(aq+0000\(aq". Note: if
+being passed through the command line will need to be quoted twice to
+allow negative offsets.
+.UNINDENT
+.TP
+.B Returns
+Returns True if successful. Otherwise False.
+.TP
+.B Return type
+\fI\%bool\fP
+.UNINDENT
.sp
CLI Example:
.INDENT 7.0
@@ -227339,6 +236654,11 @@ information about package receipts and installed applications.
.sp
New in version 2015.5.0.
+.INDENT 0.0
+.TP
+.B salt.modules.system_profiler.__virtual__()
+Check to see if the system_profiler binary is available
+.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.system_profiler.applications()
@@ -227403,6 +236723,11 @@ minion, and it is using a different module (or gives an error similar to
.UNINDENT
.INDENT 0.0
.TP
+.B salt.modules.systemd.__virtual__()
+Only work on systems that have been booted with systemd
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.systemd.available(name)
New in version 0.10.4.
@@ -228116,12 +237441,12 @@ New in version 2016.3.0.
.TP
.B configuration
This module accepts explicit telemetry credentials or
-can also read api key credentials from a pillar. More Information available at:
-.sp
-\fI\%https://github.com/mongolab/mongolab\-telemetry\-api\-docs/blob/master/alerts.md\fP
+can also read api key credentials from a pillar. More Information available
+\fI\%here\fP\&.
+.UNINDENT
.sp
In the minion\(aqs config file:
-.INDENT 7.0
+.INDENT 0.0
.INDENT 3.5
.sp
.nf
@@ -228134,6 +237459,7 @@ telemetry_api_base_url: https://telemetry\-api.mongolab.com/v0
.fi
.UNINDENT
.UNINDENT
+.INDENT 0.0
.TP
.B depends
requests
@@ -228931,6 +238257,11 @@ Module for running arbitrary tests with a __virtual__ function
Module for managing timezone on POSIX\-like systems.
.INDENT 0.0
.TP
+.B salt.modules.timezone.__virtual__()
+Only work on POSIX\-like systems
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.timezone.get_hwclock()
Get current hardware clock setting (UTC or localtime)
.sp
@@ -229115,12 +238446,8 @@ or use Self\-Signed certificates.
.INDENT 0.0
.TP
.B depends
-.INDENT 7.0
-.IP \(bu 2
-PyOpenSSL Python module (0.10 or later, 0.14 or later for
-.UNINDENT
-.sp
-X509 extension support)
+PyOpenSSL Python module (0.10 or later, 0.14 or later for X509
+extension support)
.TP
.B configuration
Add the following values in /etc/salt/minion for the CA module
@@ -229137,7 +238464,7 @@ ca.cert_base_path: \(aq/etc/pki\(aq
.UNINDENT
.UNINDENT
.sp
-CLI Example #1
+CLI Example #1:
Creating a CA, a server request and its signed certificate:
.INDENT 0.0
.INDENT 3.5
@@ -229245,6 +238572,11 @@ Created Certificate for "www.anothersometh.ing": /etc/pki/my_little/certs/someth
.UNINDENT
.INDENT 0.0
.TP
+.B salt.modules.tls.__virtual__()
+Only load this module if the ca config options are set
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.tls.ca_exists(ca_name, cacert_path=None, ca_filename=None)
Verify whether a Certificate Authority (CA) already exists
.INDENT 7.0
@@ -230225,6 +239557,11 @@ Apache Tomcat/7.0.37
.UNINDENT
.INDENT 0.0
.TP
+.B salt.modules.tomcat.__virtual__()
+Only load tomcat if it is installed or if grains/pillar config exists
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.tomcat.deploy_war(war, context, force=\(aqno\(aq, url=\(aqhttp://localhost:8080/manager\(aq, saltenv=\(aqbase\(aq, timeout=180, temp_war_location=None, version=True)
Deploy a WAR file
.INDENT 7.0
@@ -230312,10 +239649,21 @@ salt \(aq*\(aq tomcat.deploy_war /tmp/application.war /api yes http://localhost:
.INDENT 0.0
.TP
.B salt.modules.tomcat.extract_war_version(war)
-Extract the version from the war file name. There does not seem to be a
-standard for encoding the version into the \fI\%war file name\fP\&.
+Extract the version from the war file name. There does not seem to be a
+standard for encoding the version into the \fI\%war file name\fP
.sp
Examples:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+/path/salt\-2015.8.6.war \-> 2015.8.6
+/path/V6R2013xD5.war \-> None
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
@@ -231170,6 +240518,11 @@ Linux
.UNINDENT
.INDENT 0.0
.TP
+.B salt.modules.tuned.__virtual__()
+Check to see if tuned\-adm binary is installed on the system
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.tuned.active()
Return current active profile
.sp
@@ -231270,6 +240623,11 @@ my\-twilio\-account:
.UNINDENT
.INDENT 0.0
.TP
+.B salt.modules.twilio_notify.__virtual__()
+Only load this module if twilio is installed on this minion.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.twilio_notify.send_sms(profile, body, to, from_)
Send an sms
.sp
@@ -231286,6 +240644,11 @@ Manage and query udev info
.sp
New in version 2015.8.0.
+.INDENT 0.0
+.TP
+.B salt.modules.udev.__virtual__()
+Only work when udevadm is installed.
+.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.udev.env(dev)
@@ -231310,6 +240673,16 @@ salt \(aq*\(aq udev.env /sys/class/net/eth0
Return all the udev database
.sp
CLI Example:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+salt \(aq*\(aq udev.exportdb
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
@@ -231445,6 +240818,11 @@ RHEL/CentOS 6.
.UNINDENT
.INDENT 0.0
.TP
+.B salt.modules.upstart.__virtual__()
+Only work on Ubuntu
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.upstart.available(name)
Returns \fBTrue\fP if the specified service is available, otherwise returns
\fBFalse\fP\&.
@@ -231723,6 +241101,11 @@ salt \(aq*\(aq service.stop
.SS Wrapper around uptime API
.INDENT 0.0
.TP
+.B salt.modules.uptime.__virtual__()
+Only load this module if the requests python module is available
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.uptime.check_exists(name)
Check if a given URL is in being monitored by uptime
.sp
@@ -231808,6 +241191,11 @@ minion, and it is using a different module (or gives an error similar to
.UNINDENT
.INDENT 0.0
.TP
+.B salt.modules.useradd.__virtual__()
+Set the user module if the kernel is Linux, OpenBSD, NetBSD or AIX
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.useradd.add(name, uid=None, gid=None, groups=None, home=None, shell=None, unique=True, system=False, fullname=\(aq\(aq, roomnumber=\(aq\(aq, workphone=\(aq\(aq, homephone=\(aq\(aq, createhome=True, loginclass=None, root=None, nologinit=False)
Add a user to the minion
.sp
@@ -232177,6 +241565,11 @@ all
.UNINDENT
.INDENT 0.0
.TP
+.B salt.modules.uwsgi.__virtual__()
+Only load the module if uwsgi is installed
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.uwsgi.stats(socket)
Return the data from \fIuwsgi \-\-connect\-and\-read\fP as a dictionary.
.INDENT 7.0
@@ -232215,6 +241608,11 @@ from 3.x onwards
.UNINDENT
.INDENT 0.0
.TP
+.B salt.modules.varnish.__virtual__()
+Only load the module if varnish is installed
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.varnish.ban(ban_expression)
Add ban to the varnish cache
.sp
@@ -232406,6 +241804,16 @@ peer_run:
Delete secret at the path in vault. The vault policy used must allow this.
.sp
CLI Example:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+salt \(aq*\(aq vault.delete_secret "secret/my/secret"
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
@@ -232414,6 +241822,16 @@ List secret keys at the path in vault. The vault policy used must allow this.
The path should end with a trailing slash.
.sp
CLI Example:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+salt \(aq*\(aq vault.list_secrets "secret/my/"
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
@@ -232451,12 +241869,27 @@ secrets:
Set secret at the path in vault. The vault policy used must allow this.
.sp
CLI Example:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+salt \(aq*\(aq vault.write_secret "secret/my/secret" user="foo" password="bar"
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
.UNINDENT
.SS salt.modules.vbox_guest
.sp
VirtualBox Guest Additions installer
.INDENT 0.0
.TP
+.B salt.modules.vbox_guest.__virtual__()
+Set the vbox_guest module if the OS Linux
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.vbox_guest.additions_install(*args, **kwargs)
Install VirtualBox Guest Additions. Uses the CD, connected by VirtualBox.
.sp
@@ -232672,6 +242105,11 @@ virtualbox
.UNINDENT
.INDENT 0.0
.TP
+.B salt.modules.vboxmanage.__virtual__()
+Only load the module if VBoxManage is installed
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.vboxmanage.clonemedium(medium, uuid_in=None, file_in=None, uuid_out=None, file_out=None, mformat=None, variant=None, existing=False, **kwargs)
Clone a new VM from an existing VM
.sp
@@ -232951,6 +242389,11 @@ New in version 2015.8.0.
Requires an \fBapi_key\fP in \fB/etc/salt/minion\fP:
.INDENT 0.0
.TP
+.B salt.modules.victorops.__virtual__()
+Only load the module if apache is installed
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.victorops.create_event(message_type=None, routing_key=\(aqeverybody\(aq, **kwargs)
Create an event in VictorOps. Designed for use in states.
.sp
@@ -233812,13 +243255,13 @@ Options:
.IP \(bu 2
.INDENT 2.0
.TP
-\fBname\fP: Name of the snapshot. If the name is omitted, then will be used original domain name with
+.B \fBname\fP: Name of the snapshot. If the name is omitted, then will be used original domain name with
ISO 8601 time as a suffix.
.UNINDENT
.IP \(bu 2
.INDENT 2.0
.TP
-\fBsuffix\fP: Add suffix for the new name. Useful in states, where such snapshots
+.B \fBsuffix\fP: Add suffix for the new name. Useful in states, where such snapshots
can be distinguished from manually created.
.UNINDENT
.UNINDENT
@@ -234337,11 +243780,7 @@ New in version 2015.8.4.
.INDENT 0.0
.TP
.B codeauthor
-
-.nf
-:email:\(gaAlexandru Bleotu \(ga
-.fi
-
+Alexandru Bleotu <\fI\%alexandru.bleotu@morganstaley.com\fP>
.UNINDENT
.SS Dependencies
.INDENT 0.0
@@ -235160,6 +244599,11 @@ Module for listing programs that automatically run on startup
(very alpha...not tested on anything but my Win 7x64)
.INDENT 0.0
.TP
+.B salt.modules.win_autoruns.__virtual__()
+Only works on Windows systems
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.win_autoruns.list()
Get a list of automatically running programs
.sp
@@ -235191,6 +244635,11 @@ salt \(aq*\(aq certutil.add_store salt://cert.cer "TrustedPublisher"
.UNINDENT
.INDENT 0.0
.TP
+.B salt.modules.win_certutil.__virtual__()
+Only work on Windows
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.win_certutil.add_store(source, store, saltenv=\(aqbase\(aq)
Add the given cert into the given Certificate Store
.INDENT 7.0
@@ -235306,6 +244755,11 @@ winreg Python module
.UNINDENT
.INDENT 0.0
.TP
+.B salt.modules.win_dacl.__virtual__()
+Only works on Windows systems
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.win_dacl.add_ace(path, objectType, user, permission, acetype, propagation)
add an ace to an object
.sp
@@ -235585,6 +245039,11 @@ win32api Python module
.UNINDENT
.INDENT 0.0
.TP
+.B salt.modules.win_disk.__virtual__()
+Only works on Windows systems
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.win_disk.usage()
Return usage information for volumes mounted on this minion
.sp
@@ -235607,6 +245066,11 @@ not running server versions\ of Windows. Some functions are only available on
Windows 10.
.INDENT 0.0
.TP
+.B salt.modules.win_dism.__virtual__()
+Only work on Windows
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.win_dism.add_capability(capability, source=None, limit_access=False, image=None, restart=False)
Install a capability
.INDENT 7.0
@@ -235632,7 +245096,8 @@ targeted. Default is None.
.B Raises
.INDENT 7.0
.IP \(bu 2
-\fI\%NotImplementedError\fP \-\- For all versions of Windows that are not Windows 10
+\fI\%NotImplementedError\fP \-\-
+For all versions of Windows that are not Windows 10
.IP \(bu 2
and later. Server editions of Windows use ServerManager instead.
.UNINDENT
@@ -235773,7 +245238,8 @@ targeted. Default is None.
.B Raises
.INDENT 7.0
.IP \(bu 2
-\fI\%NotImplementedError\fP \-\- For all versions of Windows that are not Windows 10
+\fI\%NotImplementedError\fP \-\-
+For all versions of Windows that are not Windows 10
.IP \(bu 2
and later. Server editions of Windows use ServerManager instead.
.UNINDENT
@@ -235841,7 +245307,8 @@ targeted. Default is None.
.B Raises
.INDENT 7.0
.IP \(bu 2
-\fI\%NotImplementedError\fP \-\- For all versions of Windows that are not Windows 10
+\fI\%NotImplementedError\fP \-\-
+For all versions of Windows that are not Windows 10
.IP \(bu 2
and later. Server editions of Windows use ServerManager instead.
.UNINDENT
@@ -235934,7 +245401,8 @@ targeted. Default is None.
.B Raises
.INDENT 7.0
.IP \(bu 2
-\fI\%NotImplementedError\fP \-\- For all versions of Windows that are not Windows 10
+\fI\%NotImplementedError\fP \-\-
+For all versions of Windows that are not Windows 10
.IP \(bu 2
and later. Server editions of Windows use ServerManager instead.
.UNINDENT
@@ -236077,7 +245545,8 @@ targeted. Default is None.
.B Raises
.INDENT 7.0
.IP \(bu 2
-\fI\%NotImplementedError\fP \-\- For all versions of Windows that are not Windows 10
+\fI\%NotImplementedError\fP \-\-
+For all versions of Windows that are not Windows 10
.IP \(bu 2
and later. Server editions of Windows use ServerManager instead.
.UNINDENT
@@ -236190,6 +245659,11 @@ salt \(aq*\(aq dism.remove_package C:\epackages\epackage.cab
Module for configuring DNS Client on Windows systems
.INDENT 0.0
.TP
+.B salt.modules.win_dns_client.__virtual__()
+Only works on Windows systems
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.win_dns_client.add_dns(ip, interface=\(aqLocal Area Connection\(aq, index=1)
Add the DNS server to the network interface
(index starts from 1)
@@ -236300,6 +245774,11 @@ PowerShell 5.0
.UNINDENT
.INDENT 0.0
.TP
+.B salt.modules.win_dsc.__virtual__()
+Set the system module of the kernel is Windows
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.win_dsc.apply_config(path, source=None, salt_env=\(aqbase\(aq)
Run an compiled DSC configuration (a folder containing a .mof file). The
folder can be cached from the salt master using the \fBsource\fP option.
@@ -236460,7 +245939,8 @@ A dictionary representing the DSC Configuration on the machine
\fI\%dict\fP
.TP
.B Raises
-\fBCommandExecutionError\fP \-\- On failure
+\fBCommandExecutionError\fP \-\-
+On failure
.UNINDENT
.sp
CLI Example:
@@ -236482,12 +245962,8 @@ Get the status of the current DSC Configuration
.INDENT 7.0
.TP
.B Returns
-.INDENT 7.0
-.TP
-.B A dictionary representing the status of the current DSC
+A dictionary representing the status of the current DSC
Configuration on the machine
-.UNINDENT
-
.TP
.B Return type
\fI\%dict\fP
@@ -236512,12 +245988,8 @@ Get the current Local Configuration Manager settings
.INDENT 7.0
.TP
.B Returns
-.INDENT 7.0
-.TP
-.B A dictionary representing the Local Configuration Manager settings
+A dictionary representing the Local Configuration Manager settings
on the machine
-.UNINDENT
-
.TP
.B Return type
\fI\%dict\fP
@@ -236578,7 +246050,8 @@ True if successful
\fI\%bool\fP
.TP
.B Raises
-\fBCommandExecutionError\fP \-\- On failure
+\fBCommandExecutionError\fP \-\-
+On failure
.UNINDENT
.sp
CLI Example:
@@ -236617,7 +246090,8 @@ True if successfully restored
\fI\%bool\fP
.TP
.B Raises
-\fBCommandExecutionError\fP \-\- On failure
+\fBCommandExecutionError\fP \-\-
+On failure
.UNINDENT
.sp
CLI Example:
@@ -236738,14 +246212,9 @@ For detailed descriptions of the parameters see:
\fI\%https://msdn.microsoft.com/en\-us/PowerShell/DSC/metaConfig\fP
.INDENT 7.0
.TP
-.B Parameters
-.INDENT 7.0
-.IP \(bu 2
-\fBconfig_mode\fP (\fI\%str\fP) \-\-
-.sp
-How the LCM applies the configuration. Valid values
+.B config_mode (str): How the LCM applies the configuration. Valid values
are:
-.INDENT 2.0
+.INDENT 7.0
.IP \(bu 2
ApplyOnly
.IP \(bu 2
@@ -236753,16 +246222,16 @@ ApplyAndMonitor
.IP \(bu 2
ApplyAndAutoCorrect
.UNINDENT
-
-.IP \(bu 2
-\fBconfig_mode_freq\fP (\fI\%int\fP) \-\- How often, in minutes, the current configuration
+.TP
+.B config_mode_freq (int): How often, in minutes, the current configuration
is checked and applied. Ignored if config_mode is set to ApplyOnly.
Default is 15.
-.IP \(bu 2
-\fBrefresh_mode\fP (\fI\%str\fP) \-\-
+.UNINDENT
.sp
-How the LCM gets configurations. Valid values are:
-.INDENT 2.0
+refresh_mode (str): How the LCM gets configurations. Valid values are:
+.INDENT 7.0
+.INDENT 3.5
+.INDENT 0.0
.IP \(bu 2
Disabled
.IP \(bu 2
@@ -236770,42 +246239,39 @@ Push
.IP \(bu 2
Pull
.UNINDENT
-
-.IP \(bu 2
-\fBrefresh_freq\fP (\fI\%int\fP) \-\- How often, in minutes, the LCM checks for updated
+.UNINDENT
+.UNINDENT
+.INDENT 7.0
+.TP
+.B refresh_freq (int): How often, in minutes, the LCM checks for updated
configurations. (pull mode only) Default is 30.
-.IP \(bu 2
-\fBnote\fP (\fI\&.\fP) \-\- : Either \fIconfig_mode_freq\fP or \fIrefresh_freq\fP needs to be a
-multiple of the other. See documentation on MSDN for more details.
-.IP \(bu 2
-\fBreboot_if_needed\fP (\fI\%bool\fP) \-\- Reboot the machine if needed after a
+.TP
+.B reboot_if_needed (bool): Reboot the machine if needed after a
configuration is applied. Default is False.
-.IP \(bu 2
-\fBaction_after_reboot\fP (\fI\%str\fP) \-\-
-.sp
-Action to take after reboot. Valid values
+.TP
+.B action_after_reboot (str): Action to take after reboot. Valid values
are:
-.INDENT 2.0
+.INDENT 7.0
.IP \(bu 2
ContinueConfiguration
.IP \(bu 2
StopConfiguration
.UNINDENT
-
-.IP \(bu 2
-\fBcertificate_id\fP (\fIguid\fP) \-\- A GUID that specifies a certificate used to
+.TP
+.B certificate_id (guid): A GUID that specifies a certificate used to
access the configuration: (pull mode)
-.IP \(bu 2
-\fBconfiguration_id\fP (\fIguid\fP) \-\- A GUID that identifies the config file to get
+.TP
+.B configuration_id (guid): A GUID that identifies the config file to get
from a pull server. (pull mode)
-.IP \(bu 2
-\fBallow_module_overwrite\fP (\fI\%bool\fP) \-\- New configs are allowed to overwrite old
+.TP
+.B allow_module_overwrite (bool): New configs are allowed to overwrite old
ones on the target node.
-.IP \(bu 2
-\fBdebug_mode\fP (\fI\%str\fP) \-\-
+.UNINDENT
.sp
-Sets the debug level. Valid values are:
-.INDENT 2.0
+debug_mode (str): Sets the debug level. Valid values are:
+.INDENT 7.0
+.INDENT 3.5
+.INDENT 0.0
.IP \(bu 2
None
.IP \(bu 2
@@ -236813,11 +246279,22 @@ ForceModuleImport
.IP \(bu 2
All
.UNINDENT
-
-.IP \(bu 2
-\fBstatus_retention_days\fP (\fI\%int\fP) \-\- Number of days to keep status of the
+.UNINDENT
+.UNINDENT
+.INDENT 7.0
+.TP
+.B status_retention_days (int): Number of days to keep status of the
current config.
.UNINDENT
+.sp
+\fBNOTE:\fP
+.INDENT 7.0
+.INDENT 3.5
+Either \fBconfig_mode_freq\fP or \fBrefresh_freq\fP needs to be a
+multiple of the other. See documentation on MSDN for more details.
+.UNINDENT
+.UNINDENT
+.INDENT 7.0
.TP
.B Returns
True if successful, otherwise False
@@ -236883,6 +246360,11 @@ salt.utils.win_dacl
.UNINDENT
.INDENT 0.0
.TP
+.B salt.modules.win_file.__virtual__()
+Only works on Windows systems
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.win_file.check_perms(path, ret=None, owner=None, grant_perms=None, deny_perms=None, inheritance=True)
Set owner and permissions for each directory created. Used mostly by the
state system.
@@ -236947,7 +246429,8 @@ A dictionary of changes made to the object
\fI\%dict\fP
.TP
.B Raises
-\fBCommandExecutionError\fP \-\- If the object does not exist
+\fBCommandExecutionError\fP \-\-
+If the object does not exist
.UNINDENT
.sp
CLI Example:
@@ -237662,7 +247145,8 @@ True if successful
\fI\%bool\fP
.TP
.B Raises
-\fBCommandExecutionError\fP \-\- If unsuccessful
+\fBCommandExecutionError\fP \-\-
+If unsuccessful
.UNINDENT
.sp
CLI Example:
@@ -237827,7 +247311,8 @@ True if successful
\fI\%bool\fP
.TP
.B Raises
-\fBCommandExecutionError\fP \-\- If unsuccessful
+\fBCommandExecutionError\fP \-\-
+If unsuccessful
.UNINDENT
.sp
CLI Example:
@@ -238227,6 +247712,11 @@ salt \(aq*\(aq file.user_to_uid myusername
Module for configuring Windows Firewall using \fBnetsh\fP
.INDENT 0.0
.TP
+.B salt.modules.win_firewall.__virtual__()
+Only works on Windows systems
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.win_firewall.add_rule(name, localport, protocol=\(aqtcp\(aq, action=\(aqallow\(aq, dir=\(aqin\(aq, remoteip=\(aqany\(aq)
New in version 2015.5.0.
@@ -238318,7 +247808,8 @@ True if successful
\fI\%bool\fP
.TP
.B Raises
-\fBCommandExecutionError\fP \-\- If the command fails
+\fBCommandExecutionError\fP \-\-
+If the command fails
.UNINDENT
.sp
CLI Example:
@@ -238369,7 +247860,8 @@ True if successful
\fI\%bool\fP
.TP
.B Raises
-\fBCommandExecutionError\fP \-\- If the command fails
+\fBCommandExecutionError\fP \-\-
+If the command fails
.UNINDENT
.sp
CLI Example:
@@ -238425,7 +247917,8 @@ True if successful
\fI\%bool\fP
.TP
.B Raises
-\fBCommandExecutionError\fP \-\- If the command fails
+\fBCommandExecutionError\fP \-\-
+If the command fails
.UNINDENT
.sp
CLI Example:
@@ -238473,7 +247966,8 @@ True if successful
\fI\%bool\fP
.TP
.B Raises
-\fBCommandExecutionError\fP \-\- If the command fails
+\fBCommandExecutionError\fP \-\-
+If the command fails
.UNINDENT
.sp
CLI Example:
@@ -238501,7 +247995,8 @@ A dictionary of all profiles on the system
\fI\%dict\fP
.TP
.B Raises
-\fBCommandExecutionError\fP \-\- If the command fails
+\fBCommandExecutionError\fP \-\-
+If the command fails
.UNINDENT
.sp
CLI Example:
@@ -238536,7 +248031,8 @@ A dictionary of all rules or rules that match the name exactly
\fI\%dict\fP
.TP
.B Raises
-\fBCommandExecutionError\fP \-\- If the command fails
+\fBCommandExecutionError\fP \-\-
+If the command fails
.UNINDENT
.sp
CLI Example:
@@ -238597,6 +248093,11 @@ minion, and it is using a different module (or gives an error similar to
.UNINDENT
.INDENT 0.0
.TP
+.B salt.modules.win_groupadd.__virtual__()
+Set the group module if the kernel is Windows
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.win_groupadd.add(name, **kwargs)
Add the specified group
.INDENT 7.0
@@ -238858,6 +248359,12 @@ WebAdministration module (PowerShell) (IIS)
.sp
New in version 2016.3.0.
+.INDENT 0.0
+.TP
+.B salt.modules.win_iis.__virtual__()
+Load only on Windows
+Requires PowerShell and the WebAdministration module
+.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.win_iis.create_app(name, site, sourcepath, apppool=None)
@@ -239238,16 +248745,15 @@ salt \(aq*\(aq win_iis.get_container_setting name=\(aqMyTestPool\(aq container=\
.INDENT 0.0
.TP
.B salt.modules.win_iis.get_webapp_settings(name, site, settings)
+New in version 2017.7.0.
+
+.sp
Get the value of the setting for the IIS web application.
-.. note:
+.sp
+\fBNOTE:\fP
.INDENT 7.0
.INDENT 3.5
-.sp
-.nf
-.ft C
-Params are case sensitive.
-.ft P
-.fi
+Params are case sensitive
.UNINDENT
.UNINDENT
.INDENT 7.0
@@ -239270,19 +248776,17 @@ A dictionary of the provided settings and their values.
.B Return type
\fI\%dict\fP
.UNINDENT
-.sp
-New in version 2017.7.0.
-
.sp
CLI Example:
-.. code\-block:: bash
.INDENT 7.0
.INDENT 3.5
-.INDENT 0.0
-.TP
-.B salt \(aq*\(aq win_iis.get_webapp_settings name=\(aqapp0\(aq site=\(aqDefault Web Site\(aq
-settings="[\(aqphysicalPath\(aq,\(aqapplicationPool\(aq]"
-.UNINDENT
+.sp
+.nf
+.ft C
+salt \(aq*\(aq win_iis.get_webapp_settings name=\(aqapp0\(aq site=\(aqDefault Web Site\(aq
+ settings="[\(aqphysicalPath\(aq,\(aqapplicationPool\(aq]"
+.ft P
+.fi
.UNINDENT
.UNINDENT
.UNINDENT
@@ -239973,17 +249477,16 @@ salt \(aq*\(aq win_iis.set_container_setting name=\(aqMyTestPool\(aq container=\
.INDENT 0.0
.TP
.B salt.modules.win_iis.set_webapp_settings(name, site, settings)
+New in version 2017.7.0.
+
+.sp
Configure an IIS application.
-.. note:
+.sp
+\fBNOTE:\fP
.INDENT 7.0
.INDENT 3.5
-.sp
-.nf
-.ft C
-This function only configures existing app.
-Params are case sensitive.
-.ft P
-.fi
+This function only configures an existing app. Params are case
+sensitive.
.UNINDENT
.UNINDENT
.INDENT 7.0
@@ -239996,23 +249499,28 @@ Params are case sensitive.
\fBsite\fP (\fI\%str\fP) \-\- The IIS site name.
.IP \(bu 2
\fBsettings\fP (\fI\%str\fP) \-\- A dictionary of the setting names and their values.
+\- physicalPath: The physical path of the webapp.
+\- applicationPool: The application pool for the webapp.
+\- userName: "connectAs" user
+\- password: "connectAs" password for user
.UNINDENT
.TP
-.B Available settings
-physicalPath: The physical path of the webapp.
+.B Returns
+A boolean representing whether all changes succeeded.
+.TP
+.B Return type
+\fI\%bool\fP
.UNINDENT
.sp
-: applicationPool: The application pool for the webapp.
-: userName: "connectAs" user
-: password: "connectAs" password for user
-:return: A boolean representing whether all changes succeeded.
-:rtype: bool
-.. versionadded:: 2017.7.0
CLI Example:
-.. code\-block:: bash
.INDENT 7.0
.INDENT 3.5
-salt \(aq*\(aq win_iis.set_webapp_settings name=\(aqapp0\(aq site=\(aqsite0\(aq settings="{\(aqphysicalPath\(aq: \(aqC:site0\(aq, \(aqapppool\(aq: \(aqsite0\(aq}"
+.sp
+.nf
+.ft C
+salt \(aq*\(aq win_iis.set_webapp_settings name=\(aqapp0\(aq site=\(aqsite0\(aq settings="{\(aqphysicalPath\(aq: \(aqC:\esite0\(aq, \(aqapppool\(aq: \(aqsite0\(aq}"
+.ft P
+.fi
.UNINDENT
.UNINDENT
.UNINDENT
@@ -240145,6 +249653,11 @@ salt \(aq*\(aq win_iis.stop_site name=\(aqMy Test Site\(aq
The networking module for Windows based systems
.INDENT 0.0
.TP
+.B salt.modules.win_ip.__virtual__()
+Confine this module to Windows systems
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.win_ip.disable(iface)
Disable an interface
.sp
@@ -240450,6 +249963,11 @@ salt.modules.reg
.UNINDENT
.INDENT 0.0
.TP
+.B salt.modules.win_lgpo.__virtual__()
+Only works on Windows systems
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.win_lgpo.get(policy_class=None, return_full_policy_names=True, hierarchical_return=False, adml_language=u\(aqen\-US\(aq, return_not_configured=False)
Get a policy value
.INDENT 7.0
@@ -240726,6 +250244,11 @@ salt \(aq*\(aq license.install XXXXX\-XXXXX\-XXXXX\-XXXXX\-XXXXX
.UNINDENT
.INDENT 0.0
.TP
+.B salt.modules.win_license.__virtual__()
+Only work on Windows
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.win_license.activate()
Attempt to activate the current machine via Windows Activation
.sp
@@ -240837,6 +250360,11 @@ salt \(aq*\(aq license.uninstall
Module for gathering and managing network information
.INDENT 0.0
.TP
+.B salt.modules.win_network.__virtual__()
+Only works on Windows systems
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.win_network.connect(host, port=None, **kwargs)
Test connectivity to a host using a particular
port from the minion.
@@ -241195,6 +250723,11 @@ Management of NTP servers on Windows
.sp
New in version 2014.1.0.
+.INDENT 0.0
+.TP
+.B salt.modules.win_ntp.__virtual__()
+This only supports Windows
+.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.win_ntp.get_servers()
@@ -241238,6 +250771,11 @@ Only the ones that listen to the WM_SETTINGCHANGE message
\fI\%http://support.microsoft.com/kb/104011\fP
.INDENT 0.0
.TP
+.B salt.modules.win_path.__virtual__()
+Load only on Windows
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.win_path.add(path, index=0)
Add the directory to the SYSTEM path in the index location
.INDENT 7.0
@@ -241396,15 +250934,20 @@ old.
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
-Version numbers can be \fIversion number string\fP, \fIlatest\fP and \fINot Found\fP\&.
-Where \fINot Found\fP means this module was not able to determine the version of
-the software installed, it can also be used as the version number in sls
-definitions file in these cases. Versions numbers are sorted in order of
-0,\(gaNot Found\(ga,\(gaorder version numbers\(ga,...,\(galatest\(ga.
+Version numbers can be \fBversion number string\fP, \fBlatest\fP and \fBNot
+Found\fP, where \fBNot Found\fP means this module was not able to determine
+the version of the software installed, it can also be used as the version
+number in sls definitions file in these cases. Versions numbers are sorted
+in order of 0, \fBNot Found\fP, \fBorder version numbers\fP, ..., \fBlatest\fP\&.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
+.B salt.modules.win_pkg.__virtual__()
+Set the virtual pkg module if the os is Windows
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.win_pkg.compare_versions(ver1=u\(aq\(aq, oper=u\(aq==\(aq, ver2=u\(aq\(aq)
Compare software package versions
.INDENT 7.0
@@ -241853,21 +251396,10 @@ salt \(aq*\(aq pkg.list_available
.TP
.B salt.modules.win_pkg.list_pkgs(versions_as_list=False, **kwargs)
List the packages currently installed
-.INDENT 7.0
-.TP
-.B Parameters
-\fBversion_as_list\fP (\fI\%bool\fP) \-\- Returns the versions as a list
-.UNINDENT
-.INDENT 7.0
-.TP
-.B Kwargs:
+.sp
+version_as_list (bool): Returns the versions as a list
saltenv (str): The salt environment to use. Default \fBbase\fP\&.
-refresh (bool): Refresh package metadata. Default
-.nf
-\(ga\(ga
-.fi
-False\(ga.
-.UNINDENT
+refresh (bool): Refresh package metadata. Default \fBFalse\fP\&.
.INDENT 7.0
.TP
.B Returns
@@ -242036,15 +251568,11 @@ There is no need to call \fIpkg.refresh_db\fP every time you work with the
pkg module. Automatic refresh will occur based on the following minion
configuration settings:
.INDENT 0.0
-.INDENT 3.5
-.INDENT 0.0
.IP \(bu 2
\fIwinrepo_cache_expire_min\fP
.IP \(bu 2
\fIwinrepo_cache_expire_max\fP
.UNINDENT
-.UNINDENT
-.UNINDENT
.sp
However, if the package definition files have changed, as would be the
case if you are developing a new package definition, this function
@@ -242066,11 +251594,10 @@ one processed replaces all data from the files processed before it.
For more information see
Windows Software Repository
.sp
-Kwargs:
-.INDENT 7.0
-.INDENT 3.5
+Arguments:
+.sp
saltenv (str): Salt environment. Default: \fBbase\fP
-.INDENT 0.0
+.INDENT 7.0
.TP
.B verbose (bool):
Return a verbose data structure which includes \(aqsuccess_list\(aq, a
@@ -242082,8 +251609,6 @@ If \fBTrue\fP, an error will be raised if any repo SLS files fails to
process. If \fBFalse\fP, no error will be raised, and a dictionary
containing the full results will be returned.
.UNINDENT
-.UNINDENT
-.UNINDENT
.INDENT 7.0
.TP
.B Returns
@@ -242303,6 +251828,17 @@ dict: The package name(s) with the installed versions.
.B Return type
\fI\%str\fP
.UNINDENT
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+{[\(aq\(aq, \(aq\(aq, ]} OR
+{\(aq\(aq: [\(aq\(aq, \(aq\(aq, ]}
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
.sp
CLI Example:
.INDENT 7.0
@@ -242341,6 +251877,14 @@ PKI Client Module (Windows 8+ / Windows Server 2012+)
.sp
New in version 2016.11.0.
+.INDENT 0.0
+.TP
+.B salt.modules.win_pki.__virtual__()
+Requires Windows
+Requires Windows 8+ / Windows Server 2012+
+Requires PowerShell
+Requires PKI Client PowerShell module installed.
+.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.win_pki.export_cert(name, thumbprint, cert_format=\(aqcer\(aq, context=\(aqLocalMachine\(aq, store=\(aqMy\(aq, password=\(aq\(aq)
@@ -242619,7 +252163,9 @@ New in version 2015.8.0.
.sp
.nf
.ft C
+# Set monitor to never turn off on Battery power
salt \(aq*\(aq powercfg.set_monitor_timeout 0 power=dc
+# Set disk timeout to 120 minutes on AC power
salt \(aq*\(aq powercfg.set_disk_timeout 120 power=ac
.ft P
.fi
@@ -242627,8 +252173,41 @@ salt \(aq*\(aq powercfg.set_disk_timeout 120 power=ac
.UNINDENT
.INDENT 0.0
.TP
+.B salt.modules.win_powercfg.__virtual__()
+Only work on Windows
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.win_powercfg.get_disk_timeout(scheme=None)
Get the current disk timeout of the given scheme
+.INDENT 7.0
+.TP
+.B Parameters
+\fBscheme\fP (\fI\%str\fP) \-\-
+.sp
+The scheme to use, leave as \fBNone\fP to use the current. Default is
+\fBNone\fP\&. This can be the GUID or the Alias for the Scheme. Known
+Aliases are:
+.INDENT 7.0
+.INDENT 3.5
+.INDENT 0.0
+.IP \(bu 2
+\fBSCHEME_BALANCED\fP \- Balanced
+.IP \(bu 2
+\fBSCHEME_MAX\fP \- Power saver
+.IP \(bu 2
+\fBSCHEME_MIN\fP \- High performance
+.UNINDENT
+.UNINDENT
+.UNINDENT
+
+.TP
+.B Returns
+A dictionary of both the AC and DC settings
+.TP
+.B Return type
+\fI\%dict\fP
+.UNINDENT
.sp
CLI Example:
.INDENT 7.0
@@ -242641,16 +252220,42 @@ salt \(aq*\(aq powercfg.get_disk_timeout
.fi
.UNINDENT
.UNINDENT
-.INDENT 7.0
-.TP
-.B scheme
-The scheme to use, leave as None to use the current.
-.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.win_powercfg.get_hibernate_timeout(scheme=None)
Get the current hibernate timeout of the given scheme
+.INDENT 7.0
+.INDENT 3.5
+.INDENT 0.0
+.TP
+.B scheme (str):
+The scheme to use, leave as \fBNone\fP to use the current. Default is
+\fBNone\fP\&. This can be the GUID or the Alias for the Scheme. Known
+Aliases are:
+.INDENT 7.0
+.INDENT 3.5
+.INDENT 0.0
+.IP \(bu 2
+\fBSCHEME_BALANCED\fP \- Balanced
+.IP \(bu 2
+\fBSCHEME_MAX\fP \- Power saver
+.IP \(bu 2
+\fBSCHEME_MIN\fP \- High performance
+.UNINDENT
+.UNINDENT
+.UNINDENT
+.UNINDENT
+.UNINDENT
+.UNINDENT
+.INDENT 7.0
+.TP
+.B Returns
+A dictionary of both the AC and DC settings
+.TP
+.B Return type
+\fI\%dict\fP
+.UNINDENT
.sp
CLI Example:
.INDENT 7.0
@@ -242663,16 +252268,39 @@ salt \(aq*\(aq powercfg.get_hibernate_timeout
.fi
.UNINDENT
.UNINDENT
-.INDENT 7.0
-.TP
-.B scheme
-The scheme to use, leave as None to use the current.
-.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.win_powercfg.get_monitor_timeout(scheme=None)
Get the current monitor timeout of the given scheme
+.INDENT 7.0
+.TP
+.B Parameters
+\fBscheme\fP (\fI\%str\fP) \-\-
+.sp
+The scheme to use, leave as \fBNone\fP to use the current. Default is
+\fBNone\fP\&. This can be the GUID or the Alias for the Scheme. Known
+Aliases are:
+.INDENT 7.0
+.INDENT 3.5
+.INDENT 0.0
+.IP \(bu 2
+\fBSCHEME_BALANCED\fP \- Balanced
+.IP \(bu 2
+\fBSCHEME_MAX\fP \- Power saver
+.IP \(bu 2
+\fBSCHEME_MIN\fP \- High performance
+.UNINDENT
+.UNINDENT
+.UNINDENT
+
+.TP
+.B Returns
+A dictionary of both the AC and DC settings
+.TP
+.B Return type
+\fI\%dict\fP
+.UNINDENT
.sp
CLI Example:
.INDENT 7.0
@@ -242685,16 +252313,42 @@ salt \(aq*\(aq powercfg.get_monitor_timeout
.fi
.UNINDENT
.UNINDENT
-.INDENT 7.0
-.TP
-.B scheme
-The scheme to use, leave as None to use the current.
-.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.win_powercfg.get_standby_timeout(scheme=None)
Get the current standby timeout of the given scheme
+.INDENT 7.0
+.INDENT 3.5
+.INDENT 0.0
+.TP
+.B scheme (str):
+The scheme to use, leave as \fBNone\fP to use the current. Default is
+\fBNone\fP\&. This can be the GUID or the Alias for the Scheme. Known
+Aliases are:
+.INDENT 7.0
+.INDENT 3.5
+.INDENT 0.0
+.IP \(bu 2
+\fBSCHEME_BALANCED\fP \- Balanced
+.IP \(bu 2
+\fBSCHEME_MAX\fP \- Power saver
+.IP \(bu 2
+\fBSCHEME_MIN\fP \- High performance
+.UNINDENT
+.UNINDENT
+.UNINDENT
+.UNINDENT
+.UNINDENT
+.UNINDENT
+.INDENT 7.0
+.TP
+.B Returns
+A dictionary of both the AC and DC settings
+.TP
+.B Return type
+\fI\%dict\fP
+.UNINDENT
.sp
CLI Example:
.INDENT 7.0
@@ -242707,16 +252361,60 @@ salt \(aq*\(aq powercfg.get_standby_timeout
.fi
.UNINDENT
.UNINDENT
-.INDENT 7.0
-.TP
-.B scheme
-The scheme to use, leave as None to use the current.
-.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.win_powercfg.set_disk_timeout(timeout, power=\(aqac\(aq, scheme=None)
Set the disk timeout in minutes for the given power scheme
+.INDENT 7.0
+.TP
+.B Parameters
+.INDENT 7.0
+.IP \(bu 2
+\fBtimeout\fP (\fI\%int\fP) \-\- The amount of time in minutes before the disk will timeout
+.IP \(bu 2
+\fBpower\fP (\fI\%str\fP) \-\-
+.sp
+Set the value for AC or DC power. Default is \fBac\fP\&. Valid options
+are:
+.INDENT 2.0
+.INDENT 3.5
+.INDENT 0.0
+.IP \(bu 2
+\fBac\fP (AC Power)
+.IP \(bu 2
+\fBdc\fP (Battery)
+.UNINDENT
+.UNINDENT
+.UNINDENT
+
+.IP \(bu 2
+\fBscheme\fP (\fI\%str\fP) \-\-
+.sp
+The scheme to use, leave as \fBNone\fP to use the current. Default is
+\fBNone\fP\&. This can be the GUID or the Alias for the Scheme. Known
+Aliases are:
+.INDENT 2.0
+.INDENT 3.5
+.INDENT 0.0
+.IP \(bu 2
+\fBSCHEME_BALANCED\fP \- Balanced
+.IP \(bu 2
+\fBSCHEME_MAX\fP \- Power saver
+.IP \(bu 2
+\fBSCHEME_MIN\fP \- High performance
+.UNINDENT
+.UNINDENT
+.UNINDENT
+
+.UNINDENT
+.TP
+.B Returns
+\fBTrue\fP if successful, otherwise \fBFalse\fP
+.TP
+.B Return type
+\fI\%bool\fP
+.UNINDENT
.sp
CLI Example:
.INDENT 7.0
@@ -242724,27 +252422,66 @@ CLI Example:
.sp
.nf
.ft C
+# Sets the disk timeout to 30 minutes on battery
salt \(aq*\(aq powercfg.set_disk_timeout 30 power=dc
.ft P
.fi
.UNINDENT
.UNINDENT
-.INDENT 7.0
-.TP
-.B timeout
-The amount of time in minutes before the disk will timeout
-.TP
-.B power
-Should we set the value for AC or DC (battery)? Valid options ac,dc.
-.TP
-.B scheme
-The scheme to use, leave as None to use the current.
-.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.win_powercfg.set_hibernate_timeout(timeout, power=\(aqac\(aq, scheme=None)
Set the hibernate timeout in minutes for the given power scheme
+.INDENT 7.0
+.TP
+.B Parameters
+.INDENT 7.0
+.IP \(bu 2
+\fBtimeout\fP (\fI\%int\fP) \-\- The amount of time in minutes before the computer hibernates
+.IP \(bu 2
+\fBpower\fP (\fI\%str\fP) \-\-
+.sp
+Set the value for AC or DC power. Default is \fBac\fP\&. Valid options
+are:
+.INDENT 2.0
+.INDENT 3.5
+.INDENT 0.0
+.IP \(bu 2
+\fBac\fP (AC Power)
+.IP \(bu 2
+\fBdc\fP (Battery)
+.UNINDENT
+.UNINDENT
+.UNINDENT
+
+.IP \(bu 2
+\fBscheme\fP (\fI\%str\fP) \-\-
+.sp
+The scheme to use, leave as \fBNone\fP to use the current. Default is
+\fBNone\fP\&. This can be the GUID or the Alias for the Scheme. Known
+Aliases are:
+.INDENT 2.0
+.INDENT 3.5
+.INDENT 0.0
+.IP \(bu 2
+\fBSCHEME_BALANCED\fP \- Balanced
+.IP \(bu 2
+\fBSCHEME_MAX\fP \- Power saver
+.IP \(bu 2
+\fBSCHEME_MIN\fP \- High performance
+.UNINDENT
+.UNINDENT
+.UNINDENT
+
+.UNINDENT
+.TP
+.B Returns
+\fBTrue\fP if successful, otherwise \fBFalse\fP
+.TP
+.B Return type
+\fI\%bool\fP
+.UNINDENT
.sp
CLI Example:
.INDENT 7.0
@@ -242752,27 +252489,66 @@ CLI Example:
.sp
.nf
.ft C
-salt \(aq*\(aq powercfg.set_hibernate_timeout 30 power=pc
+# Sets the hibernate timeout to 30 minutes on Battery
+salt \(aq*\(aq powercfg.set_hibernate_timeout 30 power=dc
.ft P
.fi
.UNINDENT
.UNINDENT
-.INDENT 7.0
-.TP
-.B timeout
-The amount of time in minutes before the computer hibernates
-.TP
-.B power
-Should we set the value for AC or DC (battery)? Valid options ac,dc.
-.TP
-.B scheme
-The scheme to use, leave as None to use the current.
-.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.win_powercfg.set_monitor_timeout(timeout, power=\(aqac\(aq, scheme=None)
Set the monitor timeout in minutes for the given power scheme
+.INDENT 7.0
+.TP
+.B Parameters
+.INDENT 7.0
+.IP \(bu 2
+\fBtimeout\fP (\fI\%int\fP) \-\- The amount of time in minutes before the monitor will timeout
+.IP \(bu 2
+\fBpower\fP (\fI\%str\fP) \-\-
+.sp
+Set the value for AC or DC power. Default is \fBac\fP\&. Valid options
+are:
+.INDENT 2.0
+.INDENT 3.5
+.INDENT 0.0
+.IP \(bu 2
+\fBac\fP (AC Power)
+.IP \(bu 2
+\fBdc\fP (Battery)
+.UNINDENT
+.UNINDENT
+.UNINDENT
+
+.IP \(bu 2
+\fBscheme\fP (\fI\%str\fP) \-\-
+.sp
+The scheme to use, leave as \fBNone\fP to use the current. Default is
+\fBNone\fP\&. This can be the GUID or the Alias for the Scheme. Known
+Aliases are:
+.INDENT 2.0
+.INDENT 3.5
+.INDENT 0.0
+.IP \(bu 2
+\fBSCHEME_BALANCED\fP \- Balanced
+.IP \(bu 2
+\fBSCHEME_MAX\fP \- Power saver
+.IP \(bu 2
+\fBSCHEME_MIN\fP \- High performance
+.UNINDENT
+.UNINDENT
+.UNINDENT
+
+.UNINDENT
+.TP
+.B Returns
+\fBTrue\fP if successful, otherwise \fBFalse\fP
+.TP
+.B Return type
+\fI\%bool\fP
+.UNINDENT
.sp
CLI Example:
.INDENT 7.0
@@ -242780,27 +252556,66 @@ CLI Example:
.sp
.nf
.ft C
-salt \(aq*\(aq powercfg.set_monitor_timeout 30 power=ac
+# Sets the monitor timeout to 30 minutes
+salt \(aq*\(aq powercfg.set_monitor_timeout 30
.ft P
.fi
.UNINDENT
.UNINDENT
-.INDENT 7.0
-.TP
-.B timeout
-The amount of time in minutes before the monitor will timeout
-.TP
-.B power
-Should we set the value for AC or DC (battery)? Valid options ac,dc.
-.TP
-.B scheme
-The scheme to use, leave as None to use the current.
-.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.win_powercfg.set_standby_timeout(timeout, power=\(aqac\(aq, scheme=None)
Set the standby timeout in minutes for the given power scheme
+.INDENT 7.0
+.TP
+.B Parameters
+.INDENT 7.0
+.IP \(bu 2
+\fBtimeout\fP (\fI\%int\fP) \-\- The amount of time in minutes before the computer sleeps
+.IP \(bu 2
+\fBpower\fP (\fI\%str\fP) \-\-
+.sp
+Set the value for AC or DC power. Default is \fBac\fP\&. Valid options
+are:
+.INDENT 2.0
+.INDENT 3.5
+.INDENT 0.0
+.IP \(bu 2
+\fBac\fP (AC Power)
+.IP \(bu 2
+\fBdc\fP (Battery)
+.UNINDENT
+.UNINDENT
+.UNINDENT
+
+.IP \(bu 2
+\fBscheme\fP (\fI\%str\fP) \-\-
+.sp
+The scheme to use, leave as \fBNone\fP to use the current. Default is
+\fBNone\fP\&. This can be the GUID or the Alias for the Scheme. Known
+Aliases are:
+.INDENT 2.0
+.INDENT 3.5
+.INDENT 0.0
+.IP \(bu 2
+\fBSCHEME_BALANCED\fP \- Balanced
+.IP \(bu 2
+\fBSCHEME_MAX\fP \- Power saver
+.IP \(bu 2
+\fBSCHEME_MIN\fP \- High performance
+.UNINDENT
+.UNINDENT
+.UNINDENT
+
+.UNINDENT
+.TP
+.B Returns
+\fBTrue\fP if successful, otherwise \fBFalse\fP
+.TP
+.B Return type
+\fI\%bool\fP
+.UNINDENT
.sp
CLI Example:
.INDENT 7.0
@@ -242808,22 +252623,12 @@ CLI Example:
.sp
.nf
.ft C
+# Sets the system standby timeout to 30 minutes on Battery
salt \(aq*\(aq powercfg.set_standby_timeout 30 power=dc
.ft P
.fi
.UNINDENT
.UNINDENT
-.INDENT 7.0
-.TP
-.B timeout
-The amount of time in minutes before the computer sleeps
-.TP
-.B power
-Should we set the value for AC or DC (battery)? Valid options ac,dc.
-.TP
-.B scheme
-The scheme to use, leave as None to use the current.
-.UNINDENT
.UNINDENT
.SS salt.modules.win_psget module
.sp
@@ -242842,6 +252647,11 @@ PSGet
Support for PowerShell
.INDENT 0.0
.TP
+.B salt.modules.win_psget.__virtual__()
+Set the system module of the kernel is Windows
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.win_psget.avail_modules(desc=False)
List available modules in registered Powershell module repositories.
.INDENT 7.0
@@ -243070,6 +252880,11 @@ Module to manage Windows software repo on a Standalone Minion
For documentation on Salt\(aqs Windows Repo feature, see here\&.
.INDENT 0.0
.TP
+.B salt.modules.win_repo.__virtual__()
+Set the winrepo module if the OS is Windows
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.win_repo.genrepo()
Generate winrepo_cachefile based on sls files in the winrepo_dir
.sp
@@ -243209,6 +253024,11 @@ salt\-call winrepo.update_git_repos
Manage Windows features via the ServerManager powershell module
.INDENT 0.0
.TP
+.B salt.modules.win_servermanager.__virtual__()
+Load only on windows with servermanager module
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.win_servermanager.install(feature, recurse=False, restart=False, source=None, exclude=None)
Install a feature
.sp
@@ -243388,6 +253208,11 @@ Windows Service module.
.sp
Changed in version 2016.11.0: \- Rewritten to use PyWin32
+.INDENT 0.0
+.TP
+.B salt.modules.win_service.__virtual__()
+Only works on Windows systems with PyWin32 installed
+.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.win_service.available(name)
@@ -244354,6 +254179,11 @@ minion, and it is using a different module (or gives an error similar to
.UNINDENT
.INDENT 0.0
.TP
+.B salt.modules.win_shadow.__virtual__()
+Only works on Windows systems
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.win_shadow.info(name)
Return information for the specified user
This is just returns dummy data so that salt states can work.
@@ -244508,6 +254338,11 @@ wmi
.UNINDENT
.INDENT 0.0
.TP
+.B salt.modules.win_smtp_server.__virtual__()
+Only works on Windows systems.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.win_smtp_server.get_connection_ip_list(as_wmi_format=False, server=\(aqSmtpSvc/1\(aq)
Get the IPGrant list for the SMTP virtual server.
.INDENT 7.0
@@ -244862,6 +254697,11 @@ Module for managing SNMP service settings on Windows servers.
The Windows feature \(aqSNMP\-Service\(aq must be installed.
.INDENT 0.0
.TP
+.B salt.modules.win_snmp.__virtual__()
+Only works on Windows systems.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.win_snmp.get_agent_service_types()
Get the sysServices types that can be configured.
.INDENT 7.0
@@ -244940,6 +254780,33 @@ salt \(aq*\(aq win_snmp.get_auth_traps_enabled
.TP
.B salt.modules.win_snmp.get_community_names()
Get the current accepted SNMP community names and their permissions.
+.sp
+If community names are being managed by Group Policy, those values will be
+returned instead like this:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+TestCommunity:
+ Managed by GPO
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Community names managed normally will denote the permission instead:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+TestCommunity:
+ Read Only
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
.INDENT 7.0
.TP
.B Returns
@@ -245055,6 +254922,15 @@ salt \(aq*\(aq win_snmp.set_auth_traps_enabled status=\(aqTrue\(aq
.TP
.B salt.modules.win_snmp.set_community_names(communities)
Manage the SNMP accepted community names and their permissions.
+.sp
+\fBNOTE:\fP
+.INDENT 7.0
+.INDENT 3.5
+Settings managed by Group Policy will always take precedence over those
+set using the SNMP interface. Therefore if this function finds Group
+Policy settings it will raise a CommandExecutionError
+.UNINDENT
+.UNINDENT
.INDENT 7.0
.TP
.B Parameters
@@ -245067,6 +254943,11 @@ True if successful, otherwise False
.TP
.B Return type
\fI\%bool\fP
+.TP
+.B Raises
+\fBCommandExecutionError\fP
+.sp
+If SNMP settings are being managed by Group Policy
.UNINDENT
.sp
CLI Example:
@@ -245099,6 +254980,11 @@ wmi
.UNINDENT
.INDENT 0.0
.TP
+.B salt.modules.win_status.__virtual__()
+Only works on Windows systems with WMI and WinAPI
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.win_status.cpuload()
New in version 2015.8.0.
@@ -245272,6 +255158,11 @@ wmi
Support for reboot, shutdown, etc
.INDENT 0.0
.TP
+.B salt.modules.win_system.__virtual__()
+Only works on Windows Systems with Win32 Modules
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.win_system.get_computer_desc()
Get the Windows computer description
.INDENT 7.0
@@ -245665,7 +255556,7 @@ CLI Example:
.sp
.nf
.ft C
-salt \(aqminion\-id\(aq system.get_info
+salt \(aqminion\-id\(aq system.get_system_info
.ft P
.fi
.UNINDENT
@@ -246471,6 +256362,11 @@ You can add and clear triggers and actions.
You can list all tasks, folders, triggers, and actions.
.INDENT 0.0
.TP
+.B salt.modules.win_task.__virtual__()
+Only works on Windows systems
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.win_task.add_action(name=None, location=\(aq\e\e\(aq, action_type=\(aqExecute\(aq, **kwargs)
Add an action to a task.
.INDENT 7.0
@@ -246481,29 +256377,29 @@ Add an action to a task.
\fBname\fP (\fI\%str\fP) \-\- The name of the task to which to add the action.
.IP \(bu 2
\fBlocation\fP (\fI\%str\fP) \-\- A string value representing the location of the task.
-.UNINDENT
-.UNINDENT
-.sp
Default is \(aq\e\(aq which is the root for the task scheduler
(C:WindowsSystem32tasks).
-.INDENT 7.0
-.TP
-.B Parameters
-\fBaction_type\fP (\fI\%str\fP) \-\- The type of action to add. There are three action
-.UNINDENT
+.IP \(bu 2
+\fBaction_type\fP (\fI\%str\fP) \-\-
.sp
+The type of action to add. There are three action
types. Each one requires its own set of Keyword Arguments (kwargs). Valid
values are:
-\- Execute
-\- Email
-\- Message
+.INDENT 2.0
+.IP \(bu 2
+Execute
+.IP \(bu 2
+Email
+.IP \(bu 2
+Message
+.UNINDENT
+
+.UNINDENT
+.UNINDENT
.sp
-\fBkwargs\fP
+Required arguments for each action_type:
.sp
-Required kwargs for each value:
-.sp
-\fIExecute\fP
-Execute a command or an executable.
+\fBExecute\fP \- Execute a command or an executable
.INDENT 7.0
.TP
.B Parameters
@@ -246511,31 +256407,29 @@ Execute a command or an executable.
.IP \(bu 2
\fBcmd\fP (\fI\%str\fP) \-\- (required) The command / executable to run.
.IP \(bu 2
-\fBarguments\fP (\fI\%str\fP) \-\- (optional) Arguments to be passed to the command /
-.UNINDENT
-.UNINDENT
+\fBarguments\fP (\fI\%str\fP) \-\-
.sp
+(optional) Arguments to be passed to the command /
executable. To launch a script the first command will need to be the
interpreter for the script. For example, to run a vbscript you would
pass \fIcscript.exe\fP in the \fIcmd\fP parameter and pass the script in the
\fIarguments\fP parameter as follows:
-.INDENT 7.0
+.INDENT 2.0
.IP \(bu 2
\fBcmd=\(aqcscript.exe\(aq arguments=\(aqc:\escripts\emyscript.vbs\(aq\fP
.UNINDENT
.sp
Batch files do not need an interpreter and may be passed to the cmd
parameter directly.
-.INDENT 7.0
-.TP
-.B Parameters
+
+.IP \(bu 2
\fBstart_in\fP (\fI\%str\fP) \-\- (optional) The current working directory for the
+command.
+.UNINDENT
.UNINDENT
.sp
-command.
-.sp
-\fIEmail\fP
-Send and email. Requires \fBserver\fP, \fBfrom\fP, and \fBto\fP or \fBcc\fP\&.
+\fBEmail\fP \- Send and email. Requires \fBserver\fP, \fBfrom\fP, and \fBto\fP or
+\fBcc\fP\&.
.INDENT 7.0
.TP
.B Parameters
@@ -246558,15 +256452,14 @@ Send and email. Requires \fBserver\fP, \fBfrom\fP, and \fBto\fP or \fBcc\fP\&.
\fBserver\fP (\fI\%str\fP) \-\- The server used to send the email
.IP \(bu 2
\fBattachments\fP (\fIlist\fP) \-\- A list of attachments. These will be the paths to
+the files to attach. ie: \fBattachments="[\(aqC:\eattachment1.txt\(aq,
+\(aqC:\eattachment2.txt\(aq]"\fP
.UNINDENT
.UNINDENT
.sp
-the files to attach. ie:
-attachments=[\(aqC:attachment1.txt\(aq, \(aqC:attachment2.txt\(aq]
-.sp
-\fIMessage\fP
-Display a dialog box. The task must be set to "Run only when user is logged
-on" in order for the dialog box to display. Both parameters are required.
+\fBMessage\fP \- Display a dialog box. The task must be set to "Run only when
+user is logged on" in order for the dialog box to display. Both parameters
+are required.
.INDENT 7.0
.TP
.B Parameters
@@ -246607,148 +256500,208 @@ salt \(aqminion\-id\(aq task.add_action cmd=\(aqdel /Q /S C:\e\eTemp
\fBname\fP (\fI\%str\fP) \-\- The name of the task to which to add the trigger.
.IP \(bu 2
\fBlocation\fP (\fI\%str\fP) \-\- A string value representing the location of the task.
-.UNINDENT
-.UNINDENT
-.sp
Default is \(aq\e\(aq which is the root for the task scheduler
(C:WindowsSystem32tasks).
-.INDENT 7.0
-.TP
-.B Parameters
-\fBtrigger_type\fP (\fI\%str\fP) \-\- The type of trigger to create. This is defined when
+.IP \(bu 2
+\fBtrigger_type\fP (\fI\%str\fP) \-\- The type of trigger to create. This is defined
+when the trigger is created and cannot be changed later. Options are as
+follows:
+.UNINDENT
+.UNINDENT
+.INDENT 7.0
+.IP \(bu 2
+Event
+.IP \(bu 2
+Once
+.IP \(bu 2
+Daily
+.IP \(bu 2
+Weekly
+.IP \(bu 2
+Monthly
+.IP \(bu 2
+MonthlyDay
+.IP \(bu 2
+OnIdle
+.IP \(bu 2
+OnTaskCreation
+.IP \(bu 2
+OnBoot
+.IP \(bu 2
+OnLogon
+.IP \(bu 2
+OnSessionChange
.UNINDENT
-.sp
-the trigger is created and cannot be changed later. Options are as follows:
-\- Event
-\- Once
-\- Daily
-\- Weekly
-\- Monthly
-\- MonthlyDay
-\- OnIdle
-\- OnTaskCreation
-\- OnBoot
-\- OnLogon
-\- OnSessionChange
.INDENT 7.0
.TP
.B Parameters
+.INDENT 7.0
+.IP \(bu 2
\fBtrigger_enabled\fP (\fI\%bool\fP) \-\- Boolean value that indicates whether the
-.UNINDENT
-.sp
trigger is enabled.
-.INDENT 7.0
-.TP
-.B Parameters
+.IP \(bu 2
\fBstart_date\fP (\fI\%str\fP) \-\- The date when the trigger is activated. If no value
-.UNINDENT
-.sp
is passed, the current date will be used. Can be one of the following
formats:
-\- %Y\-%m\-%d
-\- %m\-%d\-%y
-\- %m\-%d\-%Y
-\- %m/%d/%y
-\- %m/%d/%Y
-\- %Y/%m/%d
+.UNINDENT
+.UNINDENT
+.INDENT 7.0
+.IP \(bu 2
+%Y\-%m\-%d
+.IP \(bu 2
+%m\-%d\-%y
+.IP \(bu 2
+%m\-%d\-%Y
+.IP \(bu 2
+%m/%d/%y
+.IP \(bu 2
+%m/%d/%Y
+.IP \(bu 2
+%Y/%m/%d
+.UNINDENT
.INDENT 7.0
.TP
.B Parameters
\fBstart_time\fP (\fI\%str\fP) \-\- The time when the trigger is activated. If no value
-.UNINDENT
-.sp
is passed, midnight will be used. Can be one of the following formats:
-\- %I:%M:%S %p
-\- %I:%M %p
-\- %H:%M:%S
-\- %H:%M
+.UNINDENT
+.INDENT 7.0
+.IP \(bu 2
+%I:%M:%S %p
+.IP \(bu 2
+%I:%M %p
+.IP \(bu 2
+%H:%M:%S
+.IP \(bu 2
+%H:%M
+.UNINDENT
.INDENT 7.0
.TP
.B Parameters
\fBend_date\fP (\fI\%str\fP) \-\- The date when the trigger is deactivated. The trigger
+cannot start the task after it is deactivated. Can be one of the
+following formats:
+.UNINDENT
+.INDENT 7.0
+.IP \(bu 2
+%Y\-%m\-%d
+.IP \(bu 2
+%m\-%d\-%y
+.IP \(bu 2
+%m\-%d\-%Y
+.IP \(bu 2
+%m/%d/%y
+.IP \(bu 2
+%m/%d/%Y
+.IP \(bu 2
+%Y/%m/%d
.UNINDENT
-.sp
-cannot start the task after it is deactivated. Can be one of the following
-formats:
-\- %Y\-%m\-%d
-\- %m\-%d\-%y
-\- %m\-%d\-%Y
-\- %m/%d/%y
-\- %m/%d/%Y
-\- %Y/%m/%d
.INDENT 7.0
.TP
.B Parameters
\fBend_time\fP (\fI\%str\fP) \-\- The time when the trigger is deactivated. If the this
+is not passed with \fBend_date\fP it will be set to midnight. Can be one
+of the following formats:
+.UNINDENT
+.INDENT 7.0
+.IP \(bu 2
+%I:%M:%S %p
+.IP \(bu 2
+%I:%M %p
+.IP \(bu 2
+%H:%M:%S
+.IP \(bu 2
+%H:%M
.UNINDENT
-.sp
-is not passed with \fBend_date\fP it will be set to midnight. Can be one of
-the following formats:
-\- %I:%M:%S %p
-\- %I:%M %p
-\- %H:%M:%S
-\- %H:%M
.INDENT 7.0
.TP
.B Parameters
\fBrandom_delay\fP (\fI\%str\fP) \-\- The delay time that is randomly added to the start
-.UNINDENT
-.sp
time of the trigger. Valid values are:
-\- 30 seconds
-= 1 minute
-\- 30 minutes
-= 1 hour
-\- 8 hours
-\- 1 day
+.UNINDENT
+.INDENT 7.0
+.IP \(bu 2
+30 seconds
+.IP \(bu 2
+1 minute
+.IP \(bu 2
+30 minutes
+.IP \(bu 2
+1 hour
+.IP \(bu 2
+8 hours
+.IP \(bu 2
+1 day
+.UNINDENT
.INDENT 7.0
.TP
.B Parameters
\fBrepeat_interval\fP (\fI\%str\fP) \-\- The amount of time between each restart of the
-.UNINDENT
-.sp
task. Valid values are:
-\- 5 minutes
-\- 10 minutes
-\- 15 minutes
-\- 30 minutes
-\- 1 hour
+.UNINDENT
+.INDENT 7.0
+.IP \(bu 2
+5 minutes
+.IP \(bu 2
+10 minutes
+.IP \(bu 2
+15 minutes
+.IP \(bu 2
+30 minutes
+.IP \(bu 2
+1 hour
+.UNINDENT
.INDENT 7.0
.TP
.B Parameters
\fBrepeat_duration\fP (\fI\%str\fP) \-\- How long the pattern is repeated. Valid values
-.UNINDENT
-.sp
are:
-\- Indefinitely
-\- 15 minutes
-\- 30 minutes
-\- 1 hour
-\- 12 hours
-\- 1 day
+.UNINDENT
+.INDENT 7.0
+.IP \(bu 2
+Indefinitely
+.IP \(bu 2
+15 minutes
+.IP \(bu 2
+30 minutes
+.IP \(bu 2
+1 hour
+.IP \(bu 2
+12 hours
+.IP \(bu 2
+1 day
+.UNINDENT
.INDENT 7.0
.TP
.B Parameters
+.INDENT 7.0
+.IP \(bu 2
\fBrepeat_stop_at_duration_end\fP (\fI\%bool\fP) \-\- Boolean value that indicates if a
-.UNINDENT
-.sp
running instance of the task is stopped at the end of the repetition
pattern duration.
-.INDENT 7.0
-.TP
-.B Parameters
+.IP \(bu 2
\fBexecution_time_limit\fP (\fI\%str\fP) \-\- The maximum amount of time that the task
-.UNINDENT
-.sp
launched by the trigger is allowed to run. Valid values are:
-\- 30 minutes
-\- 1 hour
-\- 2 hours
-\- 4 hours
-\- 8 hours
-\- 12 hours
-\- 1 day
-\- 3 days (default)
+.UNINDENT
+.UNINDENT
+.INDENT 7.0
+.IP \(bu 2
+30 minutes
+.IP \(bu 2
+1 hour
+.IP \(bu 2
+2 hours
+.IP \(bu 2
+4 hours
+.IP \(bu 2
+8 hours
+.IP \(bu 2
+12 hours
+.IP \(bu 2
+1 day
+.IP \(bu 2
+3 days (default)
+.UNINDENT
.sp
\fBkwargs\fP
.sp
@@ -246756,85 +256709,106 @@ There are optional keyword arguments determined by the type of trigger
being defined. They are as follows:
.sp
\fIEvent\fP
-:param str subscription: An event definition in xml format that fires
-the trigger. The easiest way to get this would is to create an event in
+.INDENT 7.0
+.TP
+.B Parameters
+\fBsubscription\fP (\fI\%str\fP) \-\- An event definition in xml format that fires the
+trigger. The easiest way to get this would is to create an event in
windows task scheduler and then copy the xml text.
+.UNINDENT
.sp
\fIOnce\fP
+.sp
No special parameters required.
.sp
\fIDaily\fP
-:param int days_interval: The interval between days in the schedule. An
+.INDENT 7.0
+.TP
+.B Parameters
+\fBdays_interval\fP (\fI\%int\fP) \-\- The interval between days in the schedule. An
interval of 1 produces a daily schedule. An interval of 2 produces an
every\-other day schedule. If no interval is specified, 1 is used. Valid
entries are 1 \- 999.
+.UNINDENT
.sp
\fIWeekly\fP
-:param int weeks_interval: The interval between weeks in the schedule.
+.INDENT 7.0
+.TP
+.B Parameters
+\fBweeks_interval\fP (\fI\%int\fP) \-\- The interval between weeks in the schedule.
An interval of 1 produces a weekly schedule. An interval of 2 produces
an every\-other week schedule. If no interval is specified, 1 is used.
Valid entries are 1 \- 52.
-.sp
-param list days_of_week: Sets the days of the week on which the task
+.UNINDENT
+.INDENT 7.0
+.TP
+.B param list days_of_week: Sets the days of the week on which the task
runs. Should be a list. ie: [\(aqMonday\(aq,\(aqWednesday\(aq,\(aqFriday\(aq]. Valid
entries are the names of the days of the week.
+.UNINDENT
.sp
\fIMonthly\fP
-:param list months_of_year: Sets the months of the year during which the
-task runs. Should be a list. ie: [\(aqJanuary\(aq,\(aqJuly\(aq]. Valid entries are
-the full names of all the months.
.INDENT 7.0
.TP
.B Parameters
+.INDENT 7.0
+.IP \(bu 2
+\fBmonths_of_year\fP (\fIlist\fP) \-\- Sets the months of the year during which the
+task runs. Should be a list. ie: [\(aqJanuary\(aq,\(aqJuly\(aq]. Valid entries are
+the full names of all the months.
+.IP \(bu 2
\fBdays_of_month\fP (\fIlist\fP) \-\- Sets the days of the month during which the
-.UNINDENT
-.sp
task runs. Should be a list. ie: [1, 15, \(aqLast\(aq]. Options are all days
of the month 1 \- 31 and the word \(aqLast\(aq to indicate the last day of the
month.
-.INDENT 7.0
-.TP
-.B Parameters
+.IP \(bu 2
\fBlast_day_of_month\fP (\fI\%bool\fP) \-\- Boolean value that indicates that the
-.UNINDENT
-.sp
task runs on the last day of the month regardless of the actual date of
that day.
+.UNINDENT
+.UNINDENT
.sp
You can set the task to run on the last day of the month by either
including the word \(aqLast\(aq in the list of days, or setting the parameter
\(aqlast_day_of_month\(ga equal to True.
.sp
\fIMonthlyDay\fP
-:param list months_of_year: Sets the months of the year during which the
+.INDENT 7.0
+.TP
+.B Parameters
+.INDENT 7.0
+.IP \(bu 2
+\fBmonths_of_year\fP (\fIlist\fP) \-\- Sets the months of the year during which the
task runs. Should be a list. ie: [\(aqJanuary\(aq,\(aqJuly\(aq]. Valid entries are
the full names of all the months.
-.INDENT 7.0
-.TP
-.B Parameters
+.IP \(bu 2
\fBweeks_of_month\fP (\fIlist\fP) \-\- Sets the weeks of the month during which the
-.UNINDENT
-.sp
task runs. Should be a list. ie: [\(aqFirst\(aq,\(aqThird\(aq]. Valid options are:
-\- First
-\- Second
-\- Third
-\- Fourth
+.UNINDENT
+.UNINDENT
+.INDENT 7.0
+.IP \(bu 2
+First
+.IP \(bu 2
+Second
+.IP \(bu 2
+Third
+.IP \(bu 2
+Fourth
+.UNINDENT
.INDENT 7.0
.TP
.B Parameters
-\fBlast_week_of_month\fP (\fI\%bool\fP) \-\- Boolean value that indicates that the
-.UNINDENT
-.sp
-task runs on the last week of the month.
.INDENT 7.0
-.TP
-.B Parameters
-\fBdays_of_week\fP (\fIlist\fP) \-\- Sets the days of the week during which the
+.IP \(bu 2
+\fBlast_week_of_month\fP (\fI\%bool\fP) \-\- Boolean value that indicates that the task
+runs on the last week of the month.
+.IP \(bu 2
+\fBdays_of_week\fP (\fIlist\fP) \-\- Sets the days of the week during which the task
+runs. Should be a list. ie: [\(aqMonday\(aq,\(aqWednesday\(aq,\(aqFriday\(aq]. Valid
+entries are the names of the days of the week.
+.UNINDENT
.UNINDENT
-.sp
-task runs. Should be a list. ie: [\(aqMonday\(aq,\(aqWednesday\(aq,\(aqFriday\(aq].
-Valid entries are the names of the days of the week.
.sp
\fIOnIdle\fP
No special parameters required.
@@ -246849,23 +256823,34 @@ No special parameters required.
No special parameters required.
.sp
\fIOnSessionChange\fP
-:param str session_user_name: Sets the user for the Terminal Server
-session. When a session state change is detected for this user, a task
-is started. To detect session status change for any user, do not pass
-this parameter.
.INDENT 7.0
.TP
.B Parameters
+.INDENT 7.0
+.IP \(bu 2
+\fBsession_user_name\fP (\fI\%str\fP) \-\- Sets the user for the Terminal Server
+session. When a session state change is detected for this user, a task
+is started. To detect session status change for any user, do not pass
+this parameter.
+.IP \(bu 2
\fBstate_change\fP (\fI\%str\fP) \-\- Sets the kind of Terminal Server session change
-.UNINDENT
-.sp
that would trigger a task launch. Valid options are:
-\- ConsoleConnect: When you connect to a user session (switch users)
-\- ConsoleDisconnect: When you disconnect a user session (switch users)
-\- RemoteConnect: When a user connects via Remote Desktop
-\- RemoteDisconnect: When a user disconnects via Remote Desktop
-\- SessionLock: When the workstation is locked
-\- SessionUnlock: When the workstation is unlocked
+.UNINDENT
+.UNINDENT
+.INDENT 7.0
+.IP \(bu 2
+ConsoleConnect: When you connect to a user session (switch users)
+.IP \(bu 2
+ConsoleDisconnect: When you disconnect a user session (switch users)
+.IP \(bu 2
+RemoteConnect: When a user connects via Remote Desktop
+.IP \(bu 2
+RemoteDisconnect: When a user disconnects via Remote Desktop
+.IP \(bu 2
+SessionLock: When the workstation is locked
+.IP \(bu 2
+SessionUnlock: When the workstation is unlocked
+.UNINDENT
.INDENT 7.0
.TP
.B Returns
@@ -246899,12 +256884,9 @@ Remove all triggers from the task.
\fBname\fP (\fI\%str\fP) \-\- The name of the task from which to clear all triggers.
.IP \(bu 2
\fBlocation\fP (\fI\%str\fP) \-\- A string value representing the location of the task.
-.UNINDENT
-.UNINDENT
-.sp
Default is \(aq\e\(aq which is the root for the task scheduler
(C:WindowsSystem32tasks).
-.INDENT 7.0
+.UNINDENT
.TP
.B Returns
True if successful, False if unsuccessful
@@ -246932,19 +256914,15 @@ Create a folder in which to create tasks.
.INDENT 7.0
.TP
.B Parameters
+.INDENT 7.0
+.IP \(bu 2
\fBname\fP (\fI\%str\fP) \-\- The name of the folder. This will be displayed in the task
-.UNINDENT
-.sp
scheduler.
-.INDENT 7.0
-.TP
-.B Parameters
+.IP \(bu 2
\fBlocation\fP (\fI\%str\fP) \-\- A string value representing the location in which to
+create the folder. Default is \(aq\e\(aq which is the root for the task
+scheduler (C:WindowsSystem32tasks).
.UNINDENT
-.sp
-create the folder. Default is \(aq\e\(aq which is the root for the task scheduler
-(C:WindowsSystem32tasks).
-.INDENT 7.0
.TP
.B Returns
True if successful, False if unsuccessful
@@ -246972,46 +256950,34 @@ Create a new task in the designated location. This function has many keyword
arguments that are not listed here. For additional arguments see:
.INDENT 7.0
.IP \(bu 2
-py:function::\fIedit_task\fP
+\fI\%edit_task()\fP
.IP \(bu 2
-py:function::\fIadd_action\fP
+\fI\%add_action()\fP
.IP \(bu 2
-py:function::\fIadd_trigger\fP
+\fI\%add_trigger()\fP
.UNINDENT
.INDENT 7.0
.TP
.B Parameters
+.INDENT 7.0
+.IP \(bu 2
\fBname\fP (\fI\%str\fP) \-\- The name of the task. This will be displayed in the task
-.UNINDENT
-.sp
scheduler.
-.INDENT 7.0
-.TP
-.B Parameters
+.IP \(bu 2
\fBlocation\fP (\fI\%str\fP) \-\- A string value representing the location in which to
-.UNINDENT
-.sp
-create the task. Default is \(aq\e\(aq which is the root for the task scheduler
-(C:WindowsSystem32tasks).
-.INDENT 7.0
-.TP
-.B Parameters
+create the task. Default is \(aq\e\(aq which is the root for the task
+scheduler (C:WindowsSystem32tasks).
+.IP \(bu 2
\fBuser_name\fP (\fI\%str\fP) \-\- The user account under which to run the task. To
-.UNINDENT
-.sp
-specify the \(aqSystem\(aq account, use \(aqSystem\(aq. The password will be ignored.
-.INDENT 7.0
-.TP
-.B Parameters
+specify the \(aqSystem\(aq account, use \(aqSystem\(aq. The password will be
+ignored.
+.IP \(bu 2
\fBpassword\fP (\fI\%str\fP) \-\- The password to use for authentication. This should set
-.UNINDENT
-.sp
-the task to run whether the user is logged in or not, but is currently not
-working.
-.INDENT 7.0
-.TP
-.B Parameters
+the task to run whether the user is logged in or not, but is currently
+not working.
+.IP \(bu 2
\fBforce\fP (\fI\%bool\fP) \-\- If the task exists, overwrite the existing task.
+.UNINDENT
.TP
.B Returns
True if successful, False if unsuccessful
@@ -247039,48 +257005,29 @@ Create a task based on XML. Source can be a file or a string of XML.
.INDENT 7.0
.TP
.B Parameters
+.INDENT 7.0
+.IP \(bu 2
\fBname\fP (\fI\%str\fP) \-\- The name of the task. This will be displayed in the task
-.UNINDENT
-.sp
scheduler.
-.INDENT 7.0
-.TP
-.B Parameters
+.IP \(bu 2
\fBlocation\fP (\fI\%str\fP) \-\- A string value representing the location in which to
-.UNINDENT
-.sp
-create the task. Default is \(aq\e\(aq which is the root for the task scheduler
-(C:WindowsSystem32tasks).
-.INDENT 7.0
-.TP
-.B Parameters
+create the task. Default is \(aq\e\(aq which is the root for the task
+scheduler (C:WindowsSystem32tasks).
+.IP \(bu 2
\fBxml_text\fP (\fI\%str\fP) \-\- A string of xml representing the task to be created.
-.UNINDENT
-.sp
This will be overridden by \fIxml_path\fP if passed.
-.INDENT 7.0
-.TP
-.B Parameters
+.IP \(bu 2
\fBxml_path\fP (\fI\%str\fP) \-\- The path to an XML file on the local system containing
-.UNINDENT
-.sp
the xml that defines the task. This will override \fIxml_text\fP
-.INDENT 7.0
-.TP
-.B Parameters
+.IP \(bu 2
\fBuser_name\fP (\fI\%str\fP) \-\- The user account under which to run the task. To
-.UNINDENT
-.sp
-specify the \(aqSystem\(aq account, use \(aqSystem\(aq. The password will be ignored.
-.INDENT 7.0
-.TP
-.B Parameters
+specify the \(aqSystem\(aq account, use \(aqSystem\(aq. The password will be
+ignored.
+.IP \(bu 2
\fBpassword\fP (\fI\%str\fP) \-\- The password to use for authentication. This should set
+the task to run whether the user is logged in or not, but is currently
+not working.
.UNINDENT
-.sp
-the task to run whether the user is logged in or not, but is currently not
-working.
-.INDENT 7.0
.TP
.B Returns
True if successful, False if unsuccessful
@@ -247112,13 +257059,10 @@ Delete a folder from the task scheduler.
.IP \(bu 2
\fBname\fP (\fI\%str\fP) \-\- The name of the folder to delete.
.IP \(bu 2
-\fBlocation\fP (\fI\%str\fP) \-\- A string value representing the location of the folder.
-.UNINDENT
-.UNINDENT
-.sp
-Default is \(aq\e\(aq which is the root for the task scheduler
+\fBlocation\fP (\fI\%str\fP) \-\- A string value representing the location of the
+folder. Default is \(aq\e\(aq which is the root for the task scheduler
(C:WindowsSystem32tasks).
-.INDENT 7.0
+.UNINDENT
.TP
.B Returns
True if successful, False if unsuccessful
@@ -247151,12 +257095,9 @@ Delete a task from the task scheduler.
\fBname\fP (\fI\%str\fP) \-\- The name of the task to delete.
.IP \(bu 2
\fBlocation\fP (\fI\%str\fP) \-\- A string value representing the location of the task.
-.UNINDENT
-.UNINDENT
-.sp
Default is \(aq\e\(aq which is the root for the task scheduler
(C:WindowsSystem32tasks).
-.INDENT 7.0
+.UNINDENT
.TP
.B Returns
True if successful, False if unsuccessful
@@ -247184,245 +257125,229 @@ Edit the parameters of a task. Triggers and Actions cannot be edited yet.
.INDENT 7.0
.TP
.B Parameters
+.INDENT 7.0
+.IP \(bu 2
\fBname\fP (\fI\%str\fP) \-\- The name of the task. This will be displayed in the task
-.UNINDENT
-.sp
scheduler.
-.INDENT 7.0
-.TP
-.B Parameters
+.IP \(bu 2
\fBlocation\fP (\fI\%str\fP) \-\- A string value representing the location in which to
-.UNINDENT
-.sp
-create the task. Default is \(aq\e\(aq which is the root for the task scheduler
-(C:WindowsSystem32tasks).
-.INDENT 7.0
-.TP
-.B Parameters
+create the task. Default is \(aq\e\(aq which is the root for the task
+scheduler (C:WindowsSystem32tasks).
+.IP \(bu 2
\fBuser_name\fP (\fI\%str\fP) \-\- The user account under which to run the task. To
-.UNINDENT
-.sp
-specify the \(aqSystem\(aq account, use \(aqSystem\(aq. The password will be ignored.
-.INDENT 7.0
-.TP
-.B Parameters
+specify the \(aqSystem\(aq account, use \(aqSystem\(aq. The password will be
+ignored.
+.IP \(bu 2
\fBpassword\fP (\fI\%str\fP) \-\- The password to use for authentication. This should set
+the task to run whether the user is logged in or not, but is currently
+not working.
+.UNINDENT
.UNINDENT
-.sp
-the task to run whether the user is logged in or not, but is currently not
-working.
.sp
\fBNOTE:\fP
.INDENT 7.0
.INDENT 3.5
-The combination of user_name and password determine how the task
+The combination of user_name and password determine how the task runs.
+For example, if a username is passed without at password the task will
+only run when the user is logged in. If a password is passed as well
+the task will run whether the user is logged on or not. If you pass
+\(aqSystem\(aq as the username the task will run as the system account (the
+password parameter is ignored.
.UNINDENT
.UNINDENT
-.sp
-runs. For example, if a username is passed without at password the task will
-only run when the user is logged in. If a password is passed as well the
-task will run whether the user is logged on or not. If you pass \(aqSystem\(aq as
-the username the task will run as the system account (the password parameter
-is ignored.
.INDENT 7.0
.TP
.B Parameters
+.INDENT 7.0
+.IP \(bu 2
\fBdescription\fP (\fI\%str\fP) \-\- A string representing the text that will be
-.UNINDENT
-.sp
displayed in the description field in the task scheduler.
-.INDENT 7.0
-.TP
-.B Parameters
+.IP \(bu 2
\fBenabled\fP (\fI\%bool\fP) \-\- A boolean value representing whether or not the task is
-.UNINDENT
-.sp
enabled.
-.INDENT 7.0
-.TP
-.B Parameters
+.IP \(bu 2
\fBhidden\fP (\fI\%bool\fP) \-\- A boolean value representing whether or not the task is
-.UNINDENT
-.sp
hidden.
-.INDENT 7.0
-.TP
-.B Parameters
+.IP \(bu 2
\fBrun_if_idle\fP (\fI\%bool\fP) \-\- Boolean value that indicates that the Task
-.UNINDENT
-.sp
Scheduler will run the task only if the computer is in an idle state.
-.INDENT 7.0
-.TP
-.B Parameters
+.IP \(bu 2
\fBidle_duration\fP (\fI\%str\fP) \-\- A value that indicates the amount of time that the
+computer must be in an idle state before the task is run. Valid values
+are:
+.UNINDENT
+.UNINDENT
+.INDENT 7.0
+.IP \(bu 2
+1 minute
+.IP \(bu 2
+5 minutes
+.IP \(bu 2
+10 minutes
+.IP \(bu 2
+15 minutes
+.IP \(bu 2
+30 minutes
+.IP \(bu 2
+1 hour
.UNINDENT
-.sp
-computer must be in an idle state before the task is run. Valid values are:
-\- 1 minute
-\- 5 minutes
-\- 10 minutes
-\- 15 minutes
-\- 30 minutes
-\- 1 hour
.INDENT 7.0
.TP
.B Parameters
\fBidle_wait_timeout\fP (\fI\%str\fP) \-\- A value that indicates the amount of time that
+the Task Scheduler will wait for an idle condition to occur. Valid
+values are:
+.UNINDENT
+.INDENT 7.0
+.IP \(bu 2
+Do not wait
+.IP \(bu 2
+1 minute
+.IP \(bu 2
+5 minutes
+.IP \(bu 2
+10 minutes
+.IP \(bu 2
+15 minutes
+.IP \(bu 2
+30 minutes
+.IP \(bu 2
+1 hour
+.IP \(bu 2
+2 hours
.UNINDENT
-.sp
-the Task Scheduler will wait for an idle condition to occur. Valid values
-are:
-\- Do not wait
-\- 1 minute
-\- 5 minutes
-\- 10 minutes
-\- 15 minutes
-\- 30 minutes
-\- 1 hour
-\- 2 hours
.INDENT 7.0
.TP
.B Parameters
+.INDENT 7.0
+.IP \(bu 2
\fBidle_stop_on_end\fP (\fI\%bool\fP) \-\- Boolean value that indicates that the Task
-.UNINDENT
-.sp
-Scheduler will terminate the task if the idle condition ends before the task
-is completed.
-.INDENT 7.0
-.TP
-.B Parameters
+Scheduler will terminate the task if the idle condition ends before the
+task is completed.
+.IP \(bu 2
\fBidle_restart\fP (\fI\%bool\fP) \-\- Boolean value that indicates whether the task is
-.UNINDENT
-.sp
-restarted when the computer cycles into an idle condition more than once.
-.INDENT 7.0
-.TP
-.B Parameters
+restarted when the computer cycles into an idle condition more than
+once.
+.IP \(bu 2
\fBac_only\fP (\fI\%bool\fP) \-\- Boolean value that indicates that the Task Scheduler
-.UNINDENT
-.sp
will launch the task only while on AC power.
-.INDENT 7.0
-.TP
-.B Parameters
+.IP \(bu 2
\fBstop_if_on_batteries\fP (\fI\%bool\fP) \-\- Boolean value that indicates that the task
-.UNINDENT
-.sp
will be stopped if the computer begins to run on battery power.
-.INDENT 7.0
-.TP
-.B Parameters
+.IP \(bu 2
\fBwake_to_run\fP (\fI\%bool\fP) \-\- Boolean value that indicates that the Task
-.UNINDENT
-.sp
Scheduler will wake the computer when it is time to run the task.
-.INDENT 7.0
-.TP
-.B Parameters
+.IP \(bu 2
\fBrun_if_network\fP (\fI\%bool\fP) \-\- Boolean value that indicates that the Task
-.UNINDENT
-.sp
Scheduler will run the task only when a network is available.
-.INDENT 7.0
-.TP
-.B Parameters
-.INDENT 7.0
.IP \(bu 2
\fBnetwork_id\fP (\fIguid\fP) \-\- GUID value that identifies a network profile.
.IP \(bu 2
\fBnetwork_name\fP (\fI\%str\fP) \-\- Sets the name of a network profile. The name is
-.UNINDENT
-.UNINDENT
-.sp
used for display purposes.
-.INDENT 7.0
-.TP
-.B Parameters
+.IP \(bu 2
\fBallow_demand_start\fP (\fI\%bool\fP) \-\- Boolean value that indicates that the task
-.UNINDENT
-.sp
can be started by using either the Run command or the Context menu.
-.INDENT 7.0
-.TP
-.B Parameters
+.IP \(bu 2
\fBstart_when_available\fP (\fI\%bool\fP) \-\- Boolean value that indicates that the Task
-.UNINDENT
-.sp
Scheduler can start the task at any time after its scheduled time has
passed.
-.INDENT 7.0
-.TP
-.B Parameters
+.IP \(bu 2
\fBrestart_every\fP \-\- A value that specifies the interval between task
-.UNINDENT
-.sp
restart attempts. Valid values are:
-:type: bool str
-\- False (to disable)
-\- 1 minute
-\- 5 minutes
-\- 10 minutes
-\- 15 minutes
-\- 30 minutes
-\- 1 hour
-\- 2 hours
+.UNINDENT
+.UNINDENT
+.INDENT 7.0
+.IP \(bu 2
+False (to disable)
+.IP \(bu 2
+1 minute
+.IP \(bu 2
+5 minutes
+.IP \(bu 2
+10 minutes
+.IP \(bu 2
+15 minutes
+.IP \(bu 2
+30 minutes
+.IP \(bu 2
+1 hour
+.IP \(bu 2
+2 hours
+.UNINDENT
.INDENT 7.0
.TP
.B Parameters
+.INDENT 7.0
+.IP \(bu 2
\fBrestart_count\fP (\fI\%int\fP) \-\- The number of times the Task Scheduler will
-.UNINDENT
-.sp
attempt to restart the task. Valid values are integers 1 \- 999.
-.INDENT 7.0
-.TP
-.B Parameters
+.IP \(bu 2
\fBexecution_time_limit\fP \-\- The amount of time allowed to complete the
-.UNINDENT
-.sp
task. Valid values are:
-:type: bool str
-\- False (to disable)
-\- 1 hour
-\- 2 hours
-\- 4 hours
-\- 8 hours
-\- 12 hours
-\- 1 day
-\- 3 days
+.UNINDENT
+.UNINDENT
+.INDENT 7.0
+.IP \(bu 2
+False (to disable)
+.IP \(bu 2
+1 hour
+.IP \(bu 2
+2 hours
+.IP \(bu 2
+4 hours
+.IP \(bu 2
+8 hours
+.IP \(bu 2
+12 hours
+.IP \(bu 2
+1 day
+.IP \(bu 2
+3 days
+.UNINDENT
.INDENT 7.0
.TP
.B Parameters
+.INDENT 7.0
+.IP \(bu 2
\fBforce_stop\fP (\fI\%bool\fP) \-\- Boolean value that indicates that the task may be
-.UNINDENT
-.sp
terminated by using TerminateProcess.
-.INDENT 7.0
-.TP
-.B Parameters
+.IP \(bu 2
\fBdelete_after\fP \-\- The amount of time that the Task Scheduler will
+wait before deleting the task after it expires. Requires a trigger with
+an expiration date. Valid values are:
+.UNINDENT
+.UNINDENT
+.INDENT 7.0
+.IP \(bu 2
+False (to disable)
+.IP \(bu 2
+Immediately
+.IP \(bu 2
+30 days
+.IP \(bu 2
+90 days
+.IP \(bu 2
+180 days
+.IP \(bu 2
+365 days
.UNINDENT
-.sp
-wait before deleting the task after it expires. Requires a trigger with an
-expiration date. Valid values are:
-:type: bool str
-\- False (to disable)
-\- Immediately
-\- 30 days
-\- 90 days
-\- 180 days
-\- 365 days
.INDENT 7.0
.TP
.B Parameters
\fBmultiple_instances\fP (\fI\%str\fP) \-\- Sets the policy that defines how the Task
-.UNINDENT
-.sp
Scheduler deals with multiple instances of the task. Valid values are:
-\- Parallel
-\- Queue
-\- No New Instance
-\- Stop Existing
+.UNINDENT
+.INDENT 7.0
+.IP \(bu 2
+Parallel
+.IP \(bu 2
+Queue
+.IP \(bu 2
+No New Instance
+.IP \(bu 2
+Stop Existing
+.UNINDENT
.INDENT 7.0
.TP
.B Returns
@@ -247456,12 +257381,9 @@ Get the details about a task in the task scheduler.
\fBname\fP (\fI\%str\fP) \-\- The name of the task for which to return the status
.IP \(bu 2
\fBlocation\fP (\fI\%str\fP) \-\- A string value representing the location of the task.
-.UNINDENT
-.UNINDENT
-.sp
Default is \(aq\e\(aq which is the root for the task scheduler
(C:WindowsSystem32tasks).
-.INDENT 7.0
+.UNINDENT
.TP
.B Returns
@@ -247494,12 +257416,9 @@ List all actions that pertain to a task in the specified location.
\fBname\fP (\fI\%str\fP) \-\- The name of the task for which list actions.
.IP \(bu 2
\fBlocation\fP (\fI\%str\fP) \-\- A string value representing the location of the task
+from which to list actions. Default is \(aq\e\(aq which is the root for the
+task scheduler (C:WindowsSystem32tasks).
.UNINDENT
-.UNINDENT
-.sp
-from which to list actions. Default is \(aq\e\(aq which is the root for the task
-scheduler (C:WindowsSystem32tasks).
-.INDENT 7.0
.TP
.B Returns
Returns a list of actions.
@@ -247528,11 +257447,8 @@ List all folders located in a specific location in the task scheduler.
.TP
.B Parameters
\fBlocation\fP (\fI\%str\fP) \-\- A string value representing the folder from which you
-.UNINDENT
-.sp
want to list tasks. Default is \(aq\e\(aq which is the root for the task
scheduler (C:WindowsSystem32tasks).
-.INDENT 7.0
.TP
.B Returns
Returns a list of folders.
@@ -247561,11 +257477,8 @@ List all tasks located in a specific location in the task scheduler.
.TP
.B Parameters
\fBlocation\fP (\fI\%str\fP) \-\- A string value representing the folder from which you
-.UNINDENT
-.sp
want to list tasks. Default is \(aq\e\(aq which is the root for the task
scheduler (C:WindowsSystem32tasks).
-.INDENT 7.0
.TP
.B Returns
Returns a list of tasks.
@@ -247598,12 +257511,9 @@ List all triggers that pertain to a task in the specified location.
\fBname\fP (\fI\%str\fP) \-\- The name of the task for which list triggers.
.IP \(bu 2
\fBlocation\fP (\fI\%str\fP) \-\- A string value representing the location of the task
+from which to list triggers. Default is \(aq\e\(aq which is the root for the
+task scheduler (C:WindowsSystem32tasks).
.UNINDENT
-.UNINDENT
-.sp
-from which to list triggers. Default is \(aq\e\(aq which is the root for the task
-scheduler (C:WindowsSystem32tasks).
-.INDENT 7.0
.TP
.B Returns
Returns a list of triggers.
@@ -247636,12 +257546,9 @@ Run a scheduled task manually.
\fBname\fP (\fI\%str\fP) \-\- The name of the task to run.
.IP \(bu 2
\fBlocation\fP (\fI\%str\fP) \-\- A string value representing the location of the task.
-.UNINDENT
-.UNINDENT
-.sp
Default is \(aq\e\(aq which is the root for the task scheduler
(C:WindowsSystem32tasks).
-.INDENT 7.0
+.UNINDENT
.TP
.B Returns
True if successful, False if unsuccessful
@@ -247674,12 +257581,9 @@ Run a scheduled task and return when the task finishes
\fBname\fP (\fI\%str\fP) \-\- The name of the task to run.
.IP \(bu 2
\fBlocation\fP (\fI\%str\fP) \-\- A string value representing the location of the task.
-.UNINDENT
-.UNINDENT
-.sp
Default is \(aq\e\(aq which is the root for the task scheduler
(C:WindowsSystem32tasks).
-.INDENT 7.0
+.UNINDENT
.TP
.B Returns
True if successful, False if unsuccessful
@@ -247712,12 +257616,9 @@ Determine the status of a task. Is it Running, Queued, Ready, etc.
\fBname\fP (\fI\%str\fP) \-\- The name of the task for which to return the status
.IP \(bu 2
\fBlocation\fP (\fI\%str\fP) \-\- A string value representing the location of the task.
-.UNINDENT
-.UNINDENT
-.sp
Default is \(aq\e\(aq which is the root for the task scheduler
(C:WindowsSystem32tasks).
-.INDENT 7.0
+.UNINDENT
.TP
.B Returns
The current status of the task. Will be one of the following:
@@ -247764,12 +257665,9 @@ Stop a scheduled task.
\fBname\fP (\fI\%str\fP) \-\- The name of the task to stop.
.IP \(bu 2
\fBlocation\fP (\fI\%str\fP) \-\- A string value representing the location of the task.
-.UNINDENT
-.UNINDENT
-.sp
Default is \(aq\e\(aq which is the root for the task scheduler
(C:WindowsSystem32tasks).
-.INDENT 7.0
+.UNINDENT
.TP
.B Returns
True if successful, False if unsuccessful
@@ -247795,6 +257693,11 @@ salt \(aqminion\-id\(aq task.list_stop
Module for managing timezone on Windows systems.
.INDENT 0.0
.TP
+.B salt.modules.win_timezone.__virtual__()
+Only load on windows
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.win_timezone.get_hwclock()
Get current hardware clock setting (UTC or localtime)
.sp
@@ -247962,9 +257865,11 @@ salt \(aq*\(aq win_update.install_updates categories="[\(aqCritical Updates\(aq,
You can also specify a number of features about the update to have a
fine grain approach to specific types of updates. These are the following
features/states of updates available for configuring:
-.. code\-block:: text
.INDENT 0.0
.INDENT 3.5
+.sp
+.nf
+.ft C
\(aqUI\(aq \- User interaction required, skipped by default
\(aqdownloaded\(aq \- Already downloaded, included by default
\(aqpresent\(aq \- Present on computer, included by default
@@ -247973,6 +257878,8 @@ features/states of updates available for configuring:
\(aqhidden\(aq \- Skip hidden updates, skipped by default
\(aqsoftware\(aq \- Software updates, included by default
\(aqdriver\(aq \- Driver updates, included by default
+.ft P
+.fi
.UNINDENT
.UNINDENT
.sp
@@ -248004,6 +257911,11 @@ it\(aqs enumeration is described here: \fI\%https://msdn.microsoft.com/en\-us/li
The result code is then followed by the update name and its KB identifier.
.INDENT 0.0
.TP
+.B salt.modules.win_update.__virtual__()
+Only works on Windows systems
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.win_update.download_updates(skips=None, retries=5, categories=None)
Downloads all available updates, skipping those that require user
interaction.
@@ -248236,6 +258148,11 @@ This currently only works with local user accounts, not domain accounts
.UNINDENT
.INDENT 0.0
.TP
+.B salt.modules.win_useradd.__virtual__()
+Requires Windows and Windows Modules
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.win_useradd.add(name, password=None, fullname=None, description=None, groups=None, home=None, homedrive=None, profile=None, logonscript=None)
Add a user to the minion.
.INDENT 7.0
@@ -248601,55 +258518,28 @@ Return user information
\fBname\fP (\fI\%str\fP) \-\- Username for which to display information
.TP
.B Returns
-.INDENT 7.0
-.TP
-.B A dictionary containing user information
-.INDENT 7.0
-.IP \(bu 2
-fullname
-.IP \(bu 2
-username
-.IP \(bu 2
-SID
-.IP \(bu 2
-passwd (will always return None)
-.IP \(bu 2
-comment (same as description, left here for backwards compatibility)
-.IP \(bu 2
-description
-.IP \(bu 2
-active
-.IP \(bu 2
-logonscript
-.IP \(bu 2
-profile
-.IP \(bu 2
-home
-.IP \(bu 2
-homedrive
-.IP \(bu 2
-groups
-.IP \(bu 2
-password_changed
-.IP \(bu 2
-successful_logon_attempts
-.IP \(bu 2
-failed_logon_attempts
-.IP \(bu 2
-last_logon
-.IP \(bu 2
-account_disabled
-.IP \(bu 2
-account_locked
-.IP \(bu 2
-password_never_expires
-.IP \(bu 2
-disallow_change_password
-.IP \(bu 2
-gid
-.UNINDENT
-.UNINDENT
-
+A dictionary containing user information
+\- fullname
+\- username
+\- SID
+\- passwd (will always return None)
+\- comment (same as description, left here for backwards compatibility)
+\- description
+\- active
+\- logonscript
+\- profile
+\- home
+\- homedrive
+\- groups
+\- password_changed
+\- successful_logon_attempts
+\- failed_logon_attempts
+\- last_logon
+\- account_disabled
+\- account_locked
+\- password_never_expires
+\- disallow_change_password
+\- gid
.TP
.B Return type
\fI\%dict\fP
@@ -248899,9 +258789,9 @@ Module for managing Windows Updates using the Windows Update Agent.
List updates on the system using the following functions:
.INDENT 0.0
.IP \(bu 2
-available
+\fI\%win_wua.available\fP
.IP \(bu 2
-list
+\fBwin_wua.list\fP
.UNINDENT
.sp
This is an easy way to find additional information about updates available to
@@ -248911,13 +258801,13 @@ Once you have the GUID or a KB number for the update you can get information
about the update, download, install, or uninstall it using these functions:
.INDENT 0.0
.IP \(bu 2
-get
+\fI\%win_wua.get\fP
.IP \(bu 2
-download
+\fI\%win_wua.download\fP
.IP \(bu 2
-install
+\fI\%win_wua.install\fP
.IP \(bu 2
-uninstall
+\fI\%win_wua.uninstall\fP
.UNINDENT
.sp
The get function expects a name in the form of a GUID, KB, or Title and should
@@ -248925,17 +258815,22 @@ return information about a single update. The other functions accept either a
single item or a list of items for downloading/installing/uninstalling a
specific list of items.
.sp
-The list and get functions are utility functions. In addition to
-returning information about updates they can also download and install updates
-by setting \fBdownload=True\fP or \fBinstall=True\fP\&. So, with list for
-example, you could run the function with the filters you want to see what is
-available. Then just add \fBinstall=True\fP to install everything on that list.
+The \fBwin_wua.list\fP and
+\fI\%win_wua.get\fP functions are utility
+functions. In addition to returning information about updates they can also
+download and install updates by setting \fBdownload=True\fP or \fBinstall=True\fP\&.
+So, with py:func:\fIwin_wua.list \fP for example, you
+could run the function with the filters you want to see what is available. Then
+just add \fBinstall=True\fP to install everything on that list.
.sp
If you want to download, install, or uninstall specific updates, use
-download, install, or uninstall\&. To update your system
-with the latest updates use list and set \fBinstall=True\fP
+\fI\%win_wua.download\fP,
+\fI\%win_wua.install\fP, or
+\fI\%win_wua.uninstall\fP\&. To update your
+system with the latest updates use \fBwin_wua.list\fP and set \fBinstall=True\fP
.sp
-You can also adjust the Windows Update settings using the set_wu_settings
+You can also adjust the Windows Update settings using the
+\fI\%win_wua.set_wu_settings\fP
function. This function is only supported on the following operating systems:
.INDENT 0.0
.IP \(bu 2
@@ -248957,10 +258852,12 @@ New in version 2015.8.0.
.INDENT 0.0
.TP
.B depends
-.INDENT 7.0
-.IP \(bu 2
salt.utils.win_update
.UNINDENT
+.INDENT 0.0
+.TP
+.B salt.modules.win_wua.__virtual__()
+Only works on Windows systems with PyWin32
.UNINDENT
.INDENT 0.0
.TP
@@ -250133,6 +260030,11 @@ M2Crypto
.UNINDENT
.INDENT 0.0
.TP
+.B salt.modules.x509.__virtual__()
+only load this module if m2crypto is available
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.x509.create_certificate(path=None, text=False, overwrite=True, ca_server=None, **kwargs)
Create an X509 certificate.
.INDENT 7.0
@@ -250256,15 +260158,7 @@ X509v3 Basic Constraints extension.
.TP
.B extensions:
The following arguments set X509v3 Extension values. If the value
-starts with
-.nf
-\(ga\(ga
-.fi
-critical
-.nf
-\(ga\(ga
-.fi
-, the extension will be marked as critical.
+starts with \fBcritical\fP, the extension will be marked as critical.
.sp
Some special extensions are \fBsubjectKeyIdentifier\fP and
\fBauthorityKeyIdentifier\fP\&.
@@ -250403,8 +260297,7 @@ CLI Example:
.sp
.nf
.ft C
-salt \(aq*\(aq x509.create_certificate path=/etc/pki/myca.crt \e
-signing_private_key=\(aq/etc/pki/myca.key\(aq csr=\(aq/etc/pki/myca.csr\(aq}
+salt \(aq*\(aq x509.create_certificate path=/etc/pki/myca.crt signing_private_key=\(aq/etc/pki/myca.key\(aq csr=\(aq/etc/pki/myca.csr\(aq}
.ft P
.fi
.UNINDENT
@@ -250482,12 +260375,7 @@ CLI Example:
.sp
.nf
.ft C
-salt \(aq*\(aq x509.create_crl path=/etc/pki/mykey.key \e
- signing_private_key=/etc/pki/ca.key \e
- signing_cert=/etc/pki/ca.crt \e
- revoked="{\(aqcompromized\-web\-key\(aq: \e
- {\(aqcertificate\(aq: \(aq/etc/pki/certs/www1.crt\(aq, \e
- \(aqrevocation_date\(aq: \(aq2015\-03\-01 00:00:00\(aq}}"
+salt \(aq*\(aq x509.create_crl path=/etc/pki/mykey.key signing_private_key=/etc/pki/ca.key signing_cert=/etc/pki/ca.crt revoked="{\(aqcompromized\-web\-key\(aq: {\(aqcertificate\(aq: \(aq/etc/pki/certs/www1.crt\(aq, \(aqrevocation_date\(aq: \(aq2015\-03\-01 00:00:00\(aq}}"
.ft P
.fi
.UNINDENT
@@ -250521,8 +260409,7 @@ CLI Example:
.sp
.nf
.ft C
-salt \(aq*\(aq x509.create_csr path=/etc/pki/myca.csr \e
- public_key=\(aq/etc/pki/myca.key\(aq CN=\(aqMy Cert
+salt \(aq*\(aq x509.create_csr path=/etc/pki/myca.csr public_key=\(aq/etc/pki/myca.key\(aq CN=\(aqMy Cert\(aq
.ft P
.fi
.UNINDENT
@@ -250641,8 +260528,7 @@ CLI Example:
.sp
.nf
.ft C
-salt \(aq*\(aq x509.get_pem_entry "\-\-\-\-\-BEGIN CERTIFICATE REQUEST\-\-\-\-\-\e
- MIICyzCC Ar8CAQI...\-\-\-\-\-END CERTIFICATE REQUEST"
+salt \(aq*\(aq x509.get_pem_entry "\-\-\-\-\-BEGIN CERTIFICATE REQUEST\-\-\-\-\-MIICyzCC Ar8CAQI...\-\-\-\-\-END CERTIFICATE REQUEST"
.ft P
.fi
.UNINDENT
@@ -250840,8 +260726,7 @@ CLI Example:
.sp
.nf
.ft C
-salt \(aq*\(aq x509.sign_remote_certificate argdic="{\(aqpublic_key\(aq: \e
- \(aq/etc/pki/www.key\(aq, \(aqsigning_policy\(aq: \(aqwww\(aq}" __pub_id=\(aqwww1\(aq
+salt \(aq*\(aq x509.sign_remote_certificate argdic="{\(aqpublic_key\(aq: \(aq/etc/pki/www.key\(aq, \(aqsigning_policy\(aq: \(aqwww\(aq}" __pub_id=\(aqwww1\(aq
.ft P
.fi
.UNINDENT
@@ -250994,9 +260879,7 @@ CLI Example:
.sp
.nf
.ft C
-salt \(aq*\(aq x509.write_pem \e
- "\-\-\-\-\-BEGIN CERTIFICATE\-\-\-\-\-MIIGMzCCBBugA..." \e
- path=/etc/pki/mycert.crt
+salt \(aq*\(aq x509.write_pem "\-\-\-\-\-BEGIN CERTIFICATE\-\-\-\-\-MIIGMzCCBBugA..." path=/etc/pki/mycert.crt
.ft P
.fi
.UNINDENT
@@ -251545,6 +261428,11 @@ Package support for XBPS package manager (used by VoidLinux)
.sp
New in version 2016.11.0.
+.INDENT 0.0
+.TP
+.B salt.modules.xbpspkg.__virtual__()
+Set the virtual pkg module if the os is Void and xbps\-install found
+.UNINDENT
.INDENT 0.0
.TP
.B salt.modules.xbpspkg.add_repo(repo, conffile=\(aq/usr/share/xbps.d/15\-saltstack.conf\(aq)
@@ -251927,6 +261815,11 @@ salt \(aq*\(aq pkg.version ...
Module for managing XFS file systems.
.INDENT 0.0
.TP
+.B salt.modules.xfs.__virtual__()
+Only work on POSIX\-like systems
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.xfs.defragment(device)
Defragment mounted XFS filesystem.
In order to mount a filesystem, device should be properly mounted and writable.
@@ -252080,7 +261973,7 @@ Filesystem geometry options:
.IP \(bu 2
.INDENT 2.0
.TP
-\fBdso\fP: Data section options. These options specify the location, size,
+.B \fBdso\fP: Data section options. These options specify the location, size,
and other parameters of the data section of the filesystem.
.UNINDENT
.IP \(bu 2
@@ -252205,6 +262098,11 @@ my\-xmpp\-login:
.UNINDENT
.INDENT 0.0
.TP
+.B salt.modules.xmpp.__virtual__()
+Only load this module if sleekxmpp is installed on this minion.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.xmpp.send_msg(recipient, message, jid=None, password=None, profile=None)
Send a message to an XMPP recipient. Designed for use in states.
.sp
@@ -252263,6 +262161,11 @@ automatically in place of YUM in Fedora 22 and newer.
.UNINDENT
.INDENT 0.0
.TP
+.B salt.modules.yumpkg.__virtual__()
+Confine this module to yum based systems
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.yumpkg.clean_metadata(**kwargs)
New in version 2014.1.0.
@@ -253839,6 +263742,11 @@ Jiri Kotlin <\fI\%jiri.kotlin@ultimum.io\fP>
.UNINDENT
.INDENT 0.0
.TP
+.B salt.modules.zabbix.__virtual__()
+Only load the module if Zabbix server is installed
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.zabbix.apiinfo_version(**connection_args)
Retrieve the version of the Zabbix API.
.sp
@@ -253871,12 +263779,18 @@ salt \(aq*\(aq zabbix.apiinfo_version
.INDENT 0.0
.TP
.B salt.modules.zabbix.host_create(host, groups, interfaces, **connection_args)
-Create new host.
-NOTE: This function accepts all standard host properties: keyword argument names differ depending on your
-zabbix version, see: \fI\%https://www.zabbix.com/documentation/2.4/manual/api/reference/host/object#host\fP
-.sp
New in version 2016.3.0.
+.sp
+Create new host
+.sp
+\fBNOTE:\fP
+.INDENT 7.0
+.INDENT 3.5
+This function accepts all standard host properties: keyword argument
+names differ depending on your zabbix version, see \fI\%here\fP\&.
+.UNINDENT
+.UNINDENT
.INDENT 7.0
.TP
.B Parameters
@@ -253894,12 +263808,12 @@ New in version 2016.3.0.
.IP \(bu 2
\fB_connection_url\fP \-\- Optional \- url of zabbix frontend (can also be set in opts, pillar, see module\(aqs docstring)
.IP \(bu 2
-\fBvisible_name\fP \-\- string with visible name of the host, use \(aqvisible_name\(aq instead of \(aqname\(aq parameter
+\fBvisible_name\fP \-\- string with visible name of the host, use
+\(aqvisible_name\(aq instead of \(aqname\(aq parameter to not mess with value
+supplied from Salt sls file.
.UNINDENT
.UNINDENT
.sp
-to not mess with value supplied from Salt sls file.
-.sp
return: ID of the created host.
.sp
CLI Example:
@@ -253993,12 +263907,18 @@ salt \(aq*\(aq zabbix.host_exists \(aqZabbix server\(aq
.INDENT 0.0
.TP
.B salt.modules.zabbix.host_get(host=None, name=None, hostids=None, **connection_args)
-Retrieve hosts according to the given parameters.
-NOTE: This function accepts all optional host.get parameters: keyword argument names differ depending on your
-zabbix version, see: \fI\%https://www.zabbix.com/documentation/2.4/manual/api/reference/host/get\fP
-.sp
New in version 2016.3.0.
+.sp
+Retrieve hosts according to the given parameters
+.sp
+\fBNOTE:\fP
+.INDENT 7.0
+.INDENT 3.5
+This function accepts all optional host.get parameters: keyword
+argument names differ depending on your zabbix version, see \fI\%here\fP\&.
+.UNINDENT
+.UNINDENT
.INDENT 7.0
.TP
.B Parameters
@@ -254063,13 +263983,20 @@ salt \(aq*\(aq zabbix.host_list
.INDENT 0.0
.TP
.B salt.modules.zabbix.host_update(hostid, **connection_args)
-Update existing hosts.
-NOTE: This function accepts all standard host and host.update properties: keyword argument names differ depending
-on your zabbix version, see: \fI\%https://www.zabbix.com/documentation/2.4/manual/api/reference/host/update\fP
-\fI\%https://www.zabbix.com/documentation/2.4/manual/api/reference/host/object#host\fP
-.sp
New in version 2016.3.0.
+.sp
+Update existing hosts
+.sp
+\fBNOTE:\fP
+.INDENT 7.0
+.INDENT 3.5
+This function accepts all standard host and host.update properties:
+keyword argument names differ depending on your zabbix version, see the
+documentation for \fI\%host objects\fP and the documentation for \fI\%updating
+hosts\fP\&.
+.UNINDENT
+.UNINDENT
.INDENT 7.0
.TP
.B Parameters
@@ -254083,12 +264010,10 @@ New in version 2016.3.0.
.IP \(bu 2
\fB_connection_url\fP \-\- Optional \- url of zabbix frontend (can also be set in opts, pillar, see module\(aqs docstring)
.IP \(bu 2
-\fBvisible_name\fP \-\- string with visible name of the host, use \(aqvisible_name\(aq instead of \(aqname\(aq parameter
+\fBvisible_name\fP \-\- string with visible name of the host, use
+\(aqvisible_name\(aq instead of \(aqname\(aq parameter to not mess with value
+supplied from Salt sls file.
.UNINDENT
-.UNINDENT
-.sp
-to not mess with value supplied from Salt sls file.
-.INDENT 7.0
.TP
.B Returns
ID of the updated host.
@@ -254105,12 +264030,18 @@ salt \(aq*\(aq zabbix.host_update 10084 name=\(aqZabbix server2\(aq
.INDENT 0.0
.TP
.B salt.modules.zabbix.hostgroup_create(name, **connection_args)
-Create a host group.
-NOTE: This function accepts all standard host group properties: keyword argument names differ depending on your
-zabbix version, see: \fI\%https://www.zabbix.com/documentation/2.4/manual/api/reference/hostgroup/object#host_group\fP
-.sp
New in version 2016.3.0.
+.sp
+Create a host group
+.sp
+\fBNOTE:\fP
+.INDENT 7.0
+.INDENT 3.5
+This function accepts all standard host group properties: keyword
+argument names differ depending on your zabbix version, see \fI\%here\fP\&.
+.UNINDENT
+.UNINDENT
.INDENT 7.0
.TP
.B Parameters
@@ -254212,12 +264143,18 @@ salt \(aq*\(aq zabbix.hostgroup_exists MyNewGroup
.INDENT 0.0
.TP
.B salt.modules.zabbix.hostgroup_get(name=None, groupids=None, hostids=None, **connection_args)
-Retrieve host groups according to the given parameters.
-NOTE: This function accepts all standard hostgroup.get properities: keyword argument names differ depending on your
-zabbix version, see: \fI\%https://www.zabbix.com/documentation/2.2/manual/api/reference/hostgroup/get\fP
-.sp
New in version 2016.3.0.
+.sp
+Retrieve host groups according to the given parameters
+.sp
+\fBNOTE:\fP
+.INDENT 7.0
+.INDENT 3.5
+This function accepts all standard hostgroup.get properities: keyword
+argument names differ depending on your zabbix version, see \fI\%here\fP\&.
+.UNINDENT
+.UNINDENT
.INDENT 7.0
.TP
.B Parameters
@@ -254286,12 +264223,18 @@ salt \(aq*\(aq zabbix.hostgroup_list
.INDENT 0.0
.TP
.B salt.modules.zabbix.hostgroup_update(groupid, name=None, **connection_args)
-Update existing hosts group.
-NOTE: This function accepts all standard host group properties: keyword argument names differ depending on your
-zabbix version, see: \fI\%https://www.zabbix.com/documentation/2.4/manual/api/reference/hostgroup/object#host_group\fP
-.sp
New in version 2016.3.0.
+.sp
+Update existing hosts group
+.sp
+\fBNOTE:\fP
+.INDENT 7.0
+.INDENT 3.5
+This function accepts all standard host group properties: keyword
+argument names differ depending on your zabbix version, see \fI\%here\fP\&.
+.UNINDENT
+.UNINDENT
.INDENT 7.0
.TP
.B Parameters
@@ -254323,12 +264266,18 @@ salt \(aq*\(aq zabbix.hostgroup_update 24 name=\(aqRenamed Name\(aq
.INDENT 0.0
.TP
.B salt.modules.zabbix.hostinterface_create(hostid, ip, dns=\(aq\(aq, main=1, type=1, useip=1, port=None, **connection_args)
-Create new host interface
-NOTE: This function accepts all standard host group interface: keyword argument names differ depending
-on your zabbix version, see: \fI\%https://www.zabbix.com/documentation/3.0/manual/api/reference/hostinterface/object\fP
-.sp
New in version 2016.3.0.
+.sp
+Create new host interface
+.sp
+\fBNOTE:\fP
+.INDENT 7.0
+.INDENT 3.5
+This function accepts all standard host group interface: keyword
+argument names differ depending on your zabbix version, see \fI\%here\fP\&.
+.UNINDENT
+.UNINDENT
.INDENT 7.0
.TP
.B Parameters
@@ -254346,15 +264295,19 @@ New in version 2016.3.0.
.IP \(bu 2
\fBtype\fP \-\- Interface type (1 \- agent; 2 \- SNMP; 3 \- IPMI; 4 \- JMX)
.IP \(bu 2
-\fBuseip\fP \-\- Whether the connection should be made via IP (0 \- connect using host DNS name; 1 \- connect using
+\fBuseip\fP \-\- Whether the connection should be made via IP (0 \- connect
+using host DNS name; 1 \- connect using host IP address for this host
+interface)
+.IP \(bu 2
+\fB_connection_user\fP \-\- Optional \- zabbix user (can also be set in opts or
+pillar, see module\(aqs docstring)
+.IP \(bu 2
+\fB_connection_password\fP \-\- Optional \- zabbix password (can also be set in
+opts or pillar, see module\(aqs docstring)
+.IP \(bu 2
+\fB_connection_url\fP \-\- Optional \- url of zabbix frontend (can also be set
+in opts, pillar, see module\(aqs docstring)
.UNINDENT
-.UNINDENT
-.sp
-host IP address for this host interface)
-:param _connection_user: Optional \- zabbix user (can also be set in opts or pillar, see module\(aqs docstring)
-:param _connection_password: Optional \- zabbix password (can also be set in opts or pillar, see module\(aqs docstring)
-:param _connection_url: Optional \- url of zabbix frontend (can also be set in opts, pillar, see module\(aqs docstring)
-.INDENT 7.0
.TP
.B Returns
ID of the created host interface, False on failure.
@@ -254404,12 +264357,19 @@ salt \(aq*\(aq zabbix.hostinterface_delete 50
.INDENT 0.0
.TP
.B salt.modules.zabbix.hostinterface_get(hostids, **connection_args)
-Retrieve host groups according to the given parameters.
-NOTE: This function accepts all standard hostinterface.get properities: keyword argument names differ depending
-on your zabbix version, see: \fI\%https://www.zabbix.com/documentation/2.4/manual/api/reference/hostinterface/get\fP
-.sp
New in version 2016.3.0.
+.sp
+Retrieve host groups according to the given parameters
+.sp
+\fBNOTE:\fP
+.INDENT 7.0
+.INDENT 3.5
+This function accepts all standard hostinterface.get properities:
+keyword argument names differ depending on your zabbix version, see
+\fI\%here\fP\&.
+.UNINDENT
+.UNINDENT
.INDENT 7.0
.TP
.B Parameters
@@ -254439,12 +264399,18 @@ salt \(aq*\(aq zabbix.hostinterface_get 101054
.INDENT 0.0
.TP
.B salt.modules.zabbix.hostinterface_update(interfaceid, **connection_args)
-Update host interface
-NOTE: This function accepts all standard hostinterface: keyword argument names differ depending on your zabbix
-version, see: \fI\%https://www.zabbix.com/documentation/2.4/manual/api/reference/hostinterface/object#host_interface\fP
-.sp
New in version 2016.3.0.
+.sp
+Update host interface
+.sp
+\fBNOTE:\fP
+.INDENT 7.0
+.INDENT 3.5
+This function accepts all standard hostinterface: keyword argument
+names differ depending on your zabbix version, see \fI\%here\fP\&.
+.UNINDENT
+.UNINDENT
.INDENT 7.0
.TP
.B Parameters
@@ -254474,9 +264440,15 @@ salt \(aq*\(aq zabbix.hostinterface_update 6 ip=0.0.0.2
.INDENT 0.0
.TP
.B salt.modules.zabbix.mediatype_create(name, mediatype, **connection_args)
-Create new mediatype.
-NOTE: This function accepts all standard mediatype properties: keyword argument names differ depending on your
-zabbix version, see: \fI\%https://www.zabbix.com/documentation/3.0/manual/api/reference/mediatype/object\fP
+Create new mediatype
+.sp
+\fBNOTE:\fP
+.INDENT 7.0
+.INDENT 3.5
+This function accepts all standard mediatype properties: keyword
+argument names differ depending on your zabbix version, see \fI\%here\fP\&.
+.UNINDENT
+.UNINDENT
.INDENT 7.0
.TP
.B Parameters
@@ -254594,9 +264566,15 @@ salt \(aq*\(aq zabbix.mediatype_get mediatypeids="[\(aq1\(aq, \(aq2\(aq, \(aq3\(
.INDENT 0.0
.TP
.B salt.modules.zabbix.mediatype_update(mediatypeid, name=False, mediatype=False, **connection_args)
-Update existing mediatype.
-NOTE: This function accepts all standard mediatype properties: keyword argument names differ depending on your
-zabbix version, see: \fI\%https://www.zabbix.com/documentation/3.0/manual/api/reference/mediatype/object\fP
+Update existing mediatype
+.sp
+\fBNOTE:\fP
+.INDENT 7.0
+.INDENT 3.5
+This function accepts all standard mediatype properties: keyword
+argument names differ depending on your zabbix version, see \fI\%here\fP\&.
+.UNINDENT
+.UNINDENT
.INDENT 7.0
.TP
.B Parameters
@@ -254747,12 +264725,18 @@ severity=63
.INDENT 0.0
.TP
.B salt.modules.zabbix.user_create(alias, passwd, usrgrps, **connection_args)
-Create new zabbix user.
-NOTE: This function accepts all standard user properties: keyword argument names differ depending on your
-zabbix version, see: \fI\%https://www.zabbix.com/documentation/2.0/manual/appendix/api/user/definitions#user\fP
-.sp
New in version 2016.3.0.
+.sp
+Create new zabbix user
+.sp
+\fBNOTE:\fP
+.INDENT 7.0
+.INDENT 3.5
+This function accepts all standard user properties: keyword argument
+names differ depending on your zabbix version, see \fI\%here\fP\&.
+.UNINDENT
+.UNINDENT
.INDENT 7.0
.TP
.B Parameters
@@ -254923,12 +264907,18 @@ salt \(aq*\(aq zabbix.user_get james
.INDENT 0.0
.TP
.B salt.modules.zabbix.user_getmedia(userids=None, **connection_args)
-Retrieve media according to the given parameters NOTE: This function accepts all standard usermedia.get properties:
-keyword argument names differ depending on your zabbix version, see:
-\fI\%https://www.zabbix.com/documentation/3.2/manual/api/reference/usermedia/get\fP
-.sp
New in version 2016.3.0.
+.sp
+Retrieve media according to the given parameters
+.sp
+\fBNOTE:\fP
+.INDENT 7.0
+.INDENT 3.5
+This function accepts all standard usermedia.get properties: keyword
+argument names differ depending on your zabbix version, see \fI\%here\fP\&.
+.UNINDENT
+.UNINDENT
.INDENT 7.0
.TP
.B Parameters
@@ -254989,12 +264979,18 @@ salt \(aq*\(aq zabbix.user_list
.INDENT 0.0
.TP
.B salt.modules.zabbix.user_update(userid, **connection_args)
-Update existing users. NOTE: This function accepts all standard user properties: keyword argument names differ
-depending on your zabbix version, see:
-\fI\%https://www.zabbix.com/documentation/2.0/manual/appendix/api/user/definitions#user\fP
-.sp
New in version 2016.3.0.
+.sp
+Update existing users
+.sp
+\fBNOTE:\fP
+.INDENT 7.0
+.INDENT 3.5
+This function accepts all standard user properties: keyword argument
+names differ depending on your zabbix version, see \fI\%here\fP\&.
+.UNINDENT
+.UNINDENT
.INDENT 7.0
.TP
.B Parameters
@@ -255024,12 +265020,18 @@ salt \(aq*\(aq zabbix.user_update 16 visible_name=\(aqJames Brown\(aq
.INDENT 0.0
.TP
.B salt.modules.zabbix.usergroup_create(name, **connection_args)
-Create new user group.
-NOTE: This function accepts all standard user group properties: keyword argument names differ depending on your
-zabbix version, see: \fI\%https://www.zabbix.com/documentation/2.0/manual/appendix/api/usergroup/definitions#user_group\fP
-.sp
New in version 2016.3.0.
+.sp
+Create new user group
+.sp
+\fBNOTE:\fP
+.INDENT 7.0
+.INDENT 3.5
+This function accepts all standard user group properties: keyword
+argument names differ depending on your zabbix version, see \fI\%here\fP\&.
+.UNINDENT
+.UNINDENT
.INDENT 7.0
.TP
.B Parameters
@@ -255127,12 +265129,18 @@ salt \(aq*\(aq zabbix.usergroup_exists Guests
.INDENT 0.0
.TP
.B salt.modules.zabbix.usergroup_get(name=None, usrgrpids=None, userids=None, **connection_args)
-Retrieve user groups according to the given parameters.
-NOTE: This function accepts all usergroup_get properties: keyword argument names differ depending on your zabbix
-version, see: \fI\%https://www.zabbix.com/documentation/2.4/manual/api/reference/usergroup/get\fP
-.sp
New in version 2016.3.0.
+.sp
+Retrieve user groups according to the given parameters
+.sp
+\fBNOTE:\fP
+.INDENT 7.0
+.INDENT 3.5
+This function accepts all usergroup_get properties: keyword argument
+names differ depending on your zabbix version, see \fI\%here\fP\&.
+.UNINDENT
+.UNINDENT
.INDENT 7.0
.TP
.B Parameters
@@ -255197,12 +265205,18 @@ salt \(aq*\(aq zabbix.usergroup_list
.INDENT 0.0
.TP
.B salt.modules.zabbix.usergroup_update(usrgrpid, **connection_args)
-Update existing user group.
-NOTE: This function accepts all standard user group properties: keyword argument names differ depending on your
-zabbix version, see: \fI\%https://www.zabbix.com/documentation/2.4/manual/api/reference/usergroup/object#user_group\fP
-.sp
New in version 2016.3.0.
+.sp
+Update existing user group
+.sp
+\fBNOTE:\fP
+.INDENT 7.0
+.INDENT 3.5
+This function accepts all standard user group properties: keyword
+argument names differ depending on your zabbix version, see \fI\%here\fP\&.
+.UNINDENT
+.UNINDENT
.INDENT 7.0
.TP
.B Parameters
@@ -255259,6 +265273,11 @@ buildout
.UNINDENT
.INDENT 0.0
.TP
+.B salt.modules.zcbuildout.__virtual__()
+Only load if buildout libs are present
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.zcbuildout.bootstrap(*a, **kw)
Run the buildout bootstrap dance (python bootstrap.py).
.INDENT 7.0
@@ -255505,6 +265524,11 @@ zenoss:
.UNINDENT
.INDENT 0.0
.TP
+.B salt.modules.zenoss.__virtual__()
+Only load if requests is installed
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.zenoss.add_device(device=None, device_class=None, collector=\(aqlocalhost\(aq, prod_state=1000)
A function to connect to a zenoss server and add a new device entry.
.INDENT 7.0
@@ -255587,6 +265611,11 @@ Nitin Madhok <\fI\%nmadhok@clemson.edu\fP>
.UNINDENT
.INDENT 0.0
.TP
+.B salt.modules.zfs.__virtual__()
+Makes sure that ZFS kernel module is loaded.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.zfs.bookmark(snapshot, bookmark)
New in version 2016.3.0.
@@ -255879,11 +265908,7 @@ New in version 2016.3.0.
Displays properties for the given datasets.
.INDENT 7.0
.TP
-.B
-.nf
-*
-.fi
-dataset
+.B dataset
string
name of snapshot(s), filesystem(s), or volume(s)
.TP
@@ -255961,11 +265986,7 @@ using the zfs destroy command return EBUSY.
string
name of tag
.TP
-.B
-.nf
-*
-.fi
-snapshot
+.B snapshot
string
name of snapshot(s)
.TP
@@ -256227,11 +266248,7 @@ snapshot by using the zfs destroy command return EBUSY.
string
name of tag
.TP
-.B
-.nf
-*
-.fi
-snapshot
+.B snapshot
string
name of snapshot(s)
.TP
@@ -256372,19 +266389,11 @@ New in version 2016.3.0.
Sets the property or list of properties to the given value(s) for each dataset.
.INDENT 7.0
.TP
-.B
-.nf
-*
-.fi
-dataset
+.B dataset
string
name of snapshot(s), filesystem(s), or volume(s)
.TP
-.B
-.nf
-*
-.fi
-properties
+.B properties
string
additional zfs properties pairs
.UNINDENT
@@ -256439,11 +266448,7 @@ New in version 2016.3.0.
Creates snapshots with the given names.
.INDENT 7.0
.TP
-.B
-.nf
-*
-.fi
-snapshot
+.B snapshot
string
name of snapshot(s)
.TP
@@ -256676,6 +266681,11 @@ New in version 2014.7.0.
Provides an interface to basic ZNC functionality
.INDENT 0.0
.TP
+.B salt.modules.znc.__virtual__()
+Only load the module if znc is installed
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.znc.buildmod(*modules)
Build module using znc\-buildmod
.sp
@@ -256768,6 +266778,12 @@ Oracle Solaris 11\(aqs zoneadm is not supported by this module!
.UNINDENT
.INDENT 0.0
.TP
+.B salt.modules.zoneadm.__virtual__()
+We are available if we are have zoneadm and are the global zone on
+Solaris 10, OmniOS, OpenIndiana, OpenSolaris, or Smartos.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.zoneadm.attach(zone, force=False, brand_opts=None)
Attach the specified zone.
.INDENT 7.0
@@ -257198,6 +267214,12 @@ Oracle Solaris 11\(aqs zonecfg is not supported by this module!
.UNINDENT
.INDENT 0.0
.TP
+.B salt.modules.zonecfg.__virtual__()
+We are available if we are have zonecfg and are the global zone on
+Solaris 10, OmniOS, OpenIndiana, OpenSolaris, or Smartos.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.zonecfg.add_resource(zone, resource_type, **kwargs)
Add a resource
.INDENT 7.0
@@ -257210,11 +267232,7 @@ name of zone
string
type of resource
.TP
-.B
-.nf
-**
-.fi
-kwargs
+.B kwargs
string|int|...
resource properties
.UNINDENT
@@ -257523,11 +267541,7 @@ type of resource
string
unique resource identifier
.TP
-.B
-.nf
-**
-.fi
-kwargs
+.B kwargs
string|int|...
resource properties
.UNINDENT
@@ -257561,22 +267575,23 @@ Nitin Madhok <\fI\%nmadhok@clemson.edu\fP>
.UNINDENT
.INDENT 0.0
.TP
+.B salt.modules.zpool.__virtual__()
+Provides zpool.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.modules.zpool.add(zpool, *vdevs, **kwargs)
Changed in version 2016.3.0.
.sp
-Add the specified vdev\(aqs to the given storage pool
+Add the specified vdevs to the given storage pool
.INDENT 7.0
.TP
.B zpool
string
name of storage pool
.TP
-.B
-.nf
-*
-.fi
-vdevs
+.B vdevs
string
one or more devices
.TP
@@ -257651,11 +267666,7 @@ Create a simple zpool, a mirrored zpool, a zpool having nested VDEVs, a hybrid z
string
name of storage pool
.TP
-.B
-.nf
-*
-.fi
-vdevs
+.B vdevs
string
one or move devices
.TP
@@ -257749,7 +267760,7 @@ Changed in version 2016.3.0.
.sp
Creates file based \fBvirtual devices\fP for a zpool
.sp
-\fB*vdevs\fP is a list of full paths for mkfile to create
+\fBvdevs\fP is a list of full paths for mkfile to create
.sp
CLI Example:
.INDENT 7.0
@@ -257865,11 +267876,7 @@ Changed in version 2016.3.0.
Export storage pools
.INDENT 7.0
.TP
-.B
-.nf
-*
-.fi
-pools
+.B pools
string
one or more storage pools to export
.TP
@@ -258168,11 +268175,7 @@ the system is rebooted. To temporarily take a device offline, use \fBtemporary=T
string
name of storage pool
.TP
-.B
-.nf
-*
-.fi
-vdevs
+.B vdevs
string
one or more devices
.TP
@@ -258209,11 +268212,7 @@ Ensure that the specified devices are online
string
name of storage pool
.TP
-.B
-.nf
-*
-.fi
-vdevs
+.B vdevs
string
one or more devices
.TP
@@ -258519,6 +268518,29 @@ Converts string wildcard to a zypper query.
.B Returns
Query range
.UNINDENT
+.INDENT 7.0
+.TP
+.B __call__(pkg_name, pkg_version)
+Convert a string wildcard to a zypper query.
+.INDENT 7.0
+.TP
+.B Parameters
+.INDENT 7.0
+.IP \(bu 2
+\fBpkg_name\fP \-\-
+.IP \(bu 2
+\fBpkg_version\fP \-\-
+.UNINDENT
+.TP
+.B Returns
+
+.UNINDENT
+.UNINDENT
+.UNINDENT
+.INDENT 0.0
+.TP
+.B salt.modules.zypper.__virtual__()
+Set the virtual pkg module if the os is openSUSE
.UNINDENT
.INDENT 0.0
.TP
@@ -259803,9 +269825,15 @@ the underlying code is changed and will output more debugging info.
.TP
.B log_access_file
Path to a file to write HTTP access logs.
+.sp
+New in version 2016.11.0.
+
.TP
.B log_error_file
Path to a file to write HTTP error logs.
+.sp
+New in version 2016.11.0.
+
.TP
.B ssl_crt
The path to a SSL certificate. (See below)
@@ -260058,8 +270086,8 @@ Fill out the remaining parameters needed for the chosen client.
.UNINDENT
.sp
The \fBclient\fP field is a reference to the main Python classes used in Salt\(aqs
-Python API. Read the full client interfaces
-documentation, but in short:
+Python API. Read the full Client APIs documentation, but
+in short:
.INDENT 0.0
.IP \(bu 2
"local" uses \fBLocalClient\fP which sends
@@ -260715,8 +270743,8 @@ Start an execution command and immediately return the job id
.UNINDENT
.UNINDENT
.sp
-lowstate data describing Salt commands must be sent in the
-request body. The \fBclient\fP option will be set to
+Lowstate data describing Salt commands must be sent in the request
+body. The \fBclient\fP option will be set to
\fBlocal_async()\fP\&.
.UNINDENT
.sp
@@ -260938,8 +270966,8 @@ Run commands bypassing the \fI\%normal session handling\fP Other than that this
.INDENT 7.0
.TP
.B POST /run
-An array of lowstate data describing Salt commands must be
-sent in the request body.
+An array of lowstate data describing Salt commands must be sent in
+the request body.
.INDENT 7.0
.TP
.B Status Codes
@@ -261945,6 +271973,367 @@ Return a dump of statistics collected from the CherryPy server
.UNINDENT
.UNINDENT
.SS rest_tornado
+.SS A Websockets add\-on to saltnado
+.INDENT 0.0
+.TP
+.B depends
+.INDENT 7.0
+.IP \(bu 2
+tornado Python module
+.UNINDENT
+.UNINDENT
+.sp
+In order to enable saltnado_websockets you must add websockets: True to your
+saltnado config block.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+rest_tornado:
+ # can be any port
+ port: 8000
+ ssl_crt: /etc/pki/api/certs/server.crt
+ # no need to specify ssl_key if cert and key
+ # are in one single file
+ ssl_key: /etc/pki/api/certs/server.key
+ debug: False
+ disable_ssl: False
+ websockets: True
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.SS All Events
+.sp
+Exposes \fBall\fP "real\-time" events from Salt\(aqs event bus on a websocket connection.
+It should be noted that "Real\-time" here means these events are made available
+to the server as soon as any salt related action (changes to minions, new jobs etc) happens.
+Clients are however assumed to be able to tolerate any network transport related latencies.
+Functionality provided by this endpoint is similar to the \fB/events\fP end point.
+.sp
+The event bus on the Salt master exposes a large variety of things, notably
+when executions are started on the master and also when minions ultimately
+return their results. This URL provides a real\-time window into a running
+Salt infrastructure. Uses websocket as the transport mechanism.
+.sp
+Exposes GET method to return websocket connections.
+All requests should include an auth token.
+A way to obtain obtain authentication tokens is shown below.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+% curl \-si localhost:8000/login \e
+ \-H "Accept: application/json" \e
+ \-d username=\(aqsalt\(aq \e
+ \-d password=\(aqsalt\(aq \e
+ \-d eauth=\(aqpam\(aq
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Which results in the response
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+{
+ "return": [{
+ "perms": [".*", "@runner", "@wheel"],
+ "start": 1400556492.277421,
+ "token": "d0ce6c1a37e99dcc0374392f272fe19c0090cca7",
+ "expire": 1400599692.277422,
+ "user": "salt",
+ "eauth": "pam"
+ }]
+}
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+In this example the \fBtoken\fP returned is \fBd0ce6c1a37e99dcc0374392f272fe19c0090cca7\fP and can be included
+in subsequent websocket requests (as part of the URL).
+.sp
+The event stream can be easily consumed via JavaScript:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+// Note, you must be authenticated!
+
+// Get the Websocket connection to Salt
+var source = new Websocket(\(aqwss://localhost:8000/all_events/d0ce6c1a37e99dcc0374392f272fe19c0090cca7\(aq);
+
+// Get Salt\(aqs "real time" event stream.
+source.onopen = function() { source.send(\(aqwebsocket client ready\(aq); };
+
+// Other handlers
+source.onerror = function(e) { console.debug(\(aqerror!\(aq, e); };
+
+// e.data represents Salt\(aqs "real time" event data as serialized JSON.
+source.onmessage = function(e) { console.debug(e.data); };
+
+// Terminates websocket connection and Salt\(aqs "real time" event stream on the server.
+source.close();
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Or via Python, using the Python module
+\fI\%websocket\-client\fP for example.
+Or the tornado
+\fI\%client\fP\&.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+# Note, you must be authenticated!
+
+from websocket import create_connection
+
+# Get the Websocket connection to Salt
+ws = create_connection(\(aqwss://localhost:8000/all_events/d0ce6c1a37e99dcc0374392f272fe19c0090cca7\(aq)
+
+# Get Salt\(aqs "real time" event stream.
+ws.send(\(aqwebsocket client ready\(aq)
+
+
+# Simple listener to print results of Salt\(aqs "real time" event stream.
+# Look at https://pypi.python.org/pypi/websocket\-client/ for more examples.
+while listening_to_events:
+ print ws.recv() # Salt\(aqs "real time" event data as serialized JSON.
+
+# Terminates websocket connection and Salt\(aqs "real time" event stream on the server.
+ws.close()
+
+# Please refer to https://github.com/liris/websocket\-client/issues/81 when using a self signed cert
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Above examples show how to establish a websocket connection to Salt and activating
+real time updates from Salt\(aqs event stream by signaling \fBwebsocket client ready\fP\&.
+.SS Formatted Events
+.sp
+Exposes \fBformatted\fP "real\-time" events from Salt\(aqs event bus on a websocket connection.
+It should be noted that "Real\-time" here means these events are made available
+to the server as soon as any salt related action (changes to minions, new jobs etc) happens.
+Clients are however assumed to be able to tolerate any network transport related latencies.
+Functionality provided by this endpoint is similar to the \fB/events\fP end point.
+.sp
+The event bus on the Salt master exposes a large variety of things, notably
+when executions are started on the master and also when minions ultimately
+return their results. This URL provides a real\-time window into a running
+Salt infrastructure. Uses websocket as the transport mechanism.
+.sp
+Formatted events parses the raw "real time" event stream and maintains
+a current view of the following:
+.INDENT 0.0
+.IP \(bu 2
+minions
+.IP \(bu 2
+jobs
+.UNINDENT
+.sp
+A change to the minions (such as addition, removal of keys or connection drops)
+or jobs is processed and clients are updated.
+Since we use salt\(aqs presence events to track minions,
+please enable \fBpresence_events\fP
+and set a small value for the \fBloop_interval\fP
+in the salt master config file.
+.sp
+Exposes GET method to return websocket connections.
+All requests should include an auth token.
+A way to obtain obtain authentication tokens is shown below.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+% curl \-si localhost:8000/login \e
+ \-H "Accept: application/json" \e
+ \-d username=\(aqsalt\(aq \e
+ \-d password=\(aqsalt\(aq \e
+ \-d eauth=\(aqpam\(aq
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Which results in the response
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+{
+ "return": [{
+ "perms": [".*", "@runner", "@wheel"],
+ "start": 1400556492.277421,
+ "token": "d0ce6c1a37e99dcc0374392f272fe19c0090cca7",
+ "expire": 1400599692.277422,
+ "user": "salt",
+ "eauth": "pam"
+ }]
+}
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+In this example the \fBtoken\fP returned is \fBd0ce6c1a37e99dcc0374392f272fe19c0090cca7\fP and can be included
+in subsequent websocket requests (as part of the URL).
+.sp
+The event stream can be easily consumed via JavaScript:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+// Note, you must be authenticated!
+
+// Get the Websocket connection to Salt
+var source = new Websocket(\(aqwss://localhost:8000/formatted_events/d0ce6c1a37e99dcc0374392f272fe19c0090cca7\(aq);
+
+// Get Salt\(aqs "real time" event stream.
+source.onopen = function() { source.send(\(aqwebsocket client ready\(aq); };
+
+// Other handlers
+source.onerror = function(e) { console.debug(\(aqerror!\(aq, e); };
+
+// e.data represents Salt\(aqs "real time" event data as serialized JSON.
+source.onmessage = function(e) { console.debug(e.data); };
+
+// Terminates websocket connection and Salt\(aqs "real time" event stream on the server.
+source.close();
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Or via Python, using the Python module
+\fI\%websocket\-client\fP for example.
+Or the tornado
+\fI\%client\fP\&.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+# Note, you must be authenticated!
+
+from websocket import create_connection
+
+# Get the Websocket connection to Salt
+ws = create_connection(\(aqwss://localhost:8000/formatted_events/d0ce6c1a37e99dcc0374392f272fe19c0090cca7\(aq)
+
+# Get Salt\(aqs "real time" event stream.
+ws.send(\(aqwebsocket client ready\(aq)
+
+
+# Simple listener to print results of Salt\(aqs "real time" event stream.
+# Look at https://pypi.python.org/pypi/websocket\-client/ for more examples.
+while listening_to_events:
+ print ws.recv() # Salt\(aqs "real time" event data as serialized JSON.
+
+# Terminates websocket connection and Salt\(aqs "real time" event stream on the server.
+ws.close()
+
+# Please refer to https://github.com/liris/websocket\-client/issues/81 when using a self signed cert
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Above examples show how to establish a websocket connection to Salt and activating
+real time updates from Salt\(aqs event stream by signaling \fBwebsocket client ready\fP\&.
+.SS Example responses
+.sp
+\fBMinion information\fP is a dictionary keyed by each connected minion\(aqs \fBid\fP (\fBmid\fP),
+grains information for each minion is also included.
+.sp
+Minion information is sent in response to the following minion events:
+.INDENT 0.0
+.IP \(bu 2
+.INDENT 2.0
+.TP
+.B connection drops
+.INDENT 7.0
+.IP \(bu 2
+requires running \fBmanage.present\fP periodically every \fBloop_interval\fP seconds
+.UNINDENT
+.UNINDENT
+.IP \(bu 2
+minion addition
+.IP \(bu 2
+minon removal
+.UNINDENT
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+# Not all grains are shown
+data: {
+ "minions": {
+ "minion1": {
+ "id": "minion1",
+ "grains": {
+ "kernel": "Darwin",
+ "domain": "local",
+ "zmqversion": "4.0.3",
+ "kernelrelease": "13.2.0"
+ }
+ }
+ }
+}
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+\fBJob information\fP is also tracked and delivered.
+.sp
+Job information is also a dictionary
+in which each job\(aqs information is keyed by salt\(aqs \fBjid\fP\&.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+data: {
+ "jobs": {
+ "20140609153646699137": {
+ "tgt_type": "glob",
+ "jid": "20140609153646699137",
+ "tgt": "*",
+ "start_time": "2014\-06\-09T15:36:46.700315",
+ "state": "complete",
+ "fun": "test.ping",
+ "minions": {
+ "minion1": {
+ "return": true,
+ "retcode": 0,
+ "success": true
+ }
+ }
+ }
+ }
+}
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.SS Setup
.SS REST URI Reference
.INDENT 0.0
.IP \(bu 2
@@ -261963,12 +272352,47 @@ Return a dump of statistics collected from the CherryPy server
\fI\%/hook\fP
.UNINDENT
.SS \fB/\fP
+.INDENT 0.0
+.TP
+.B salt.netapi.rest_tornado.saltnado.SaltAPIHandler
+alias of \fB\fP
+.UNINDENT
.SS \fB/login\fP
+.INDENT 0.0
+.TP
+.B salt.netapi.rest_tornado.saltnado.SaltAuthHandler
+alias of \fB\fP
+.UNINDENT
.SS \fB/minions\fP
+.INDENT 0.0
+.TP
+.B salt.netapi.rest_tornado.saltnado.MinionSaltAPIHandler
+alias of \fB\fP
+.UNINDENT
.SS \fB/jobs\fP
+.INDENT 0.0
+.TP
+.B salt.netapi.rest_tornado.saltnado.JobsSaltAPIHandler
+alias of \fB\fP
+.UNINDENT
.SS \fB/run\fP
+.INDENT 0.0
+.TP
+.B salt.netapi.rest_tornado.saltnado.RunSaltAPIHandler
+alias of \fB\fP
+.UNINDENT
.SS \fB/events\fP
+.INDENT 0.0
+.TP
+.B salt.netapi.rest_tornado.saltnado.EventsSaltAPIHandler
+alias of \fB\fP
+.UNINDENT
.SS \fB/hook\fP
+.INDENT 0.0
+.TP
+.B salt.netapi.rest_tornado.saltnado.WebhookSaltAPIHandler
+alias of \fB\fP
+.UNINDENT
.SS rest_wsgi
.SS A minimalist REST API for Salt
.sp
@@ -262287,22 +272711,18 @@ error and no changes, otherwise full output will be used.
.IP \(bu 2
If \fBfilter\fP is used, then either or both of two different filters can be
used: \fBexclude\fP or \fBterse\fP\&.
-* for \fBexclude\fP, state.highstate expects a list of states to be excluded
.INDENT 2.0
-.INDENT 3.5
+.IP \(bu 2
+for \fBexclude\fP, state.highstate expects a list of states to be excluded
(or \fBNone\fP)
followed by \fBTrue\fP for terse output or \fBFalse\fP for regular output.
Because of parsing nuances, if only one of these is used, it must still
contain a comma. For instance: \fIexclude=True,\fP\&.
-.UNINDENT
-.UNINDENT
-.INDENT 2.0
.IP \(bu 2
for \fBterse\fP, state.highstate expects simply \fBTrue\fP or \fBFalse\fP\&.
+These can be set as such from the command line, or in the Salt config
+as \fIstate_output_exclude\fP or \fIstate_output_terse\fP, respectively.
.UNINDENT
-.sp
-These can be set as such from the command line, or in the Salt config as
-\fIstate_output_exclude\fP or \fIstate_output_terse\fP, respectively.
.UNINDENT
.TP
.B state_tabular:
@@ -262438,6 +272858,11 @@ single\-line output format and to parse each line individually. Example output
.UNINDENT
.INDENT 0.0
.TP
+.B salt.output.json_out.__virtual__()
+Rename to json
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.output.json_out.output(data, **kwargs)
Print the output data in JSON
.UNINDENT
@@ -262633,8 +273058,7 @@ Display ret data
.SS salt.output.overstatestage
.SS Display clean output of an overstate stage
.sp
-This outputter is used to display OverState stages,
-and should not be called directly.
+This outputter is used to display Orchestrate Runner stages, and should not be called directly.
.INDENT 0.0
.TP
.B salt.output.overstatestage.output(data, **kwargs)
@@ -262716,6 +273140,11 @@ Example output:
.UNINDENT
.INDENT 0.0
.TP
+.B salt.output.pprint_out.__virtual__()
+Change the name to pprint
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.output.pprint_out.output(data, **kwargs)
Print out via pretty print
.UNINDENT
@@ -262844,35 +273273,15 @@ Display the output as table.
.IP \(bu 2
\fBrow_delimiter\fP (\fI*\fP) \-\- character to separate rows. Default: \fB_\fP\&.
.IP \(bu 2
-\fBdelim\fP (\fI*\fP) \-\- character to separate columns. Default: \(ga\(ga |
-.nf
-\(ga\(ga
-.fi
-\&.
+\fBdelim\fP (\fI*\fP) \-\- character to separate columns. Default: \fB" | "\fP\&.
.IP \(bu 2
\fBjustify\fP (\fI*\fP) \-\- text alignment. Default: \fBcenter\fP\&.
.IP \(bu 2
\fBseparate_rows\fP (\fI*\fP) \-\- boolean specifying if row separator will be displayed between consecutive rows. Default: True.
.IP \(bu 2
-\fBprefix\fP (\fI*\fP) \-\- character at the beginning of the row. Default:
-.nf
-\(ga\(ga
-.fi
-|
-.nf
-\(ga\(ga
-.fi
-\&.
+\fBprefix\fP (\fI*\fP) \-\- character at the beginning of the row. Default: \fB"| "\fP\&.
.IP \(bu 2
-\fBsuffix\fP (\fI*\fP) \-\- character at the end of the row. Default: \(ga\(ga
-.nf
-|
-.fi
-
-.nf
-\(ga\(ga
-.fi
-\&.
+\fBsuffix\fP (\fI*\fP) \-\- character at the end of the row. Default: \fB" |"\fP\&.
.IP \(bu 2
\fBwidth\fP (\fI*\fP) \-\- column max width. Default: \fB50\fP\&.
.IP \(bu 2
@@ -263304,6 +273713,11 @@ confidant\-common, confidant\-client
.SS Module Documentation
.INDENT 0.0
.TP
+.B salt.pillar.confidant.__virtual__()
+Only return if requests and boto are installed.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.pillar.confidant.ext_pillar(minion_id, pillar, profile=None)
Read pillar data from Confidant via its API.
.UNINDENT
@@ -263495,6 +273909,11 @@ ext_pillar:
.UNINDENT
.INDENT 0.0
.TP
+.B salt.pillar.consul_pillar.__virtual__()
+Only return if python\-consul is installed
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.pillar.consul_pillar.consul_fetch(client, path)
Query consul for all keys/values within base path
.UNINDENT
@@ -263524,6 +273943,9 @@ merge it with the current pillar data
.SS salt.pillar.csvpillar module
.sp
Store key/value pairs in a CSV file
+.sp
+New in version 2016.11.0.
+
.sp
Example configuration:
.INDENT 0.0
@@ -263669,6 +274091,11 @@ ext_pillar:
.UNINDENT
.INDENT 0.0
.TP
+.B salt.pillar.digicert.__virtual__()
+No special requirements outside of Salt itself
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.pillar.digicert.ext_pillar(minion_id, pillar, conf)
Return an existing set of certificates
.UNINDENT
@@ -263781,6 +274208,11 @@ ext_pillar:
.SS Module Documentation
.INDENT 0.0
.TP
+.B salt.pillar.django_orm.__virtual__()
+Always load
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.pillar.django_orm.ext_pillar(minion_id, pillar, pillar_name, project_path, settings_module, django_app, env=None, env_file=None, *args, **kwargs)
Connect to a Django database through the ORM and retrieve model fields
.INDENT 7.0
@@ -263858,6 +274290,12 @@ returns a list of key/value pairs for all of the EC2 tags assigned to
the instance.
.INDENT 0.0
.TP
+.B salt.pillar.ec2_pillar.__virtual__()
+Check for required version of boto and make this pillar available
+depending on outcome.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.pillar.ec2_pillar.ext_pillar(minion_id, pillar, use_grain=False, minion_ids=None, tag_match_key=None, tag_match_value=\(aqasis\(aq, tag_list_key=None, tag_list_sep=\(aq;\(aq)
Execute a command and read the output as YAML
.UNINDENT
@@ -263966,6 +274404,11 @@ etcdctl set /salt\-private/special_minion_id/mykey my_other_value
.UNINDENT
.INDENT 0.0
.TP
+.B salt.pillar.etcd_pillar.__virtual__()
+Only return if python\-etcd is installed
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.pillar.etcd_pillar.ext_pillar(minion_id, pillar, conf)
Check etcd for all data
.UNINDENT
@@ -264094,11 +274537,7 @@ pillar module will be available for that Minion.
Changed in version 2017.7.0: Templating/rendering has been added. You can now specify a default
render pipeline and a black\- and whitelist of (dis)allowed renderers.
.sp
-
-.nf
-:param:\(gatemplate\(ga
-.fi
- must be set to \fBTrue\fP for templating to happen.
+\fBtemplate\fP must be set to \fBTrue\fP for templating to happen.
.INDENT 7.0
.INDENT 3.5
.sp
@@ -264140,11 +274579,7 @@ Defaults to \fBFalse\fP\&.
.INDENT 2.0
.INDENT 3.5
Care should be exercised when enabling this option as it will
-follow links that point outside of
-.nf
-:param:\(garoot_dir\(ga
-.fi
-\&.
+follow links that point outside of \fBroot_dir\fP\&.
.UNINDENT
.UNINDENT
.sp
@@ -264176,11 +274611,7 @@ earlier releases, \fBraw_data\fP must be used. Also, this parameter
can now be a list of globs, allowing for more granular control over
which pillar values keep their end\-of\-file newline. The globs match
paths relative to the directories named for Minion IDs and
-Nodegroup namess underneath the
-.nf
-:param:\(garoot_dir\(ga
-.fi
-\&.
+Nodegroup namess underneath the \fBroot_dir\fP\&.
.INDENT 2.0
.INDENT 3.5
.sp
@@ -264310,6 +274741,11 @@ Further information can be found on \fI\%GitHub\fP\&.
.SS Module Documentation
.INDENT 0.0
.TP
+.B salt.pillar.foreman.__virtual__()
+Only return if all the modules are available
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.pillar.foreman.ext_pillar(minion_id, pillar, key=None, only=())
Read pillar data from Foreman via its API.
.UNINDENT
@@ -264907,6 +275343,11 @@ file in the same pillar environment.
.UNINDENT
.INDENT 0.0
.TP
+.B salt.pillar.git_pillar.__virtual__()
+Only load if gitpython is available
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.pillar.git_pillar.ext_pillar(minion_id, repo, pillar_dirs)
Checkout the ext_pillar sources and compile the resulting pillar SLS
.UNINDENT
@@ -264975,6 +275416,11 @@ Ensure we are using the latest revision in the hg repository
.UNINDENT
.INDENT 0.0
.TP
+.B salt.pillar.hg_pillar.__virtual__()
+Only load if hglib is available.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.pillar.hg_pillar.ext_pillar(minion_id, pillar, repo, branch=\(aqdefault\(aq, root=None)
Extract pillar from an hg repository
.UNINDENT
@@ -264988,6 +275434,11 @@ Execute an hg pull on all the repos
Use hiera data as a Pillar source
.INDENT 0.0
.TP
+.B salt.pillar.hiera.__virtual__()
+Only return if hiera is installed
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.pillar.hiera.ext_pillar(minion_id, pillar, conf)
Execute hiera and return the data
.UNINDENT
@@ -265872,6 +276323,11 @@ _
.TE
.INDENT 0.0
.TP
+.B salt.pillar.makostack.__virtual__()
+Set up the libcloud functions and check for EC2 configurations
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.pillar.makostack.ext_pillar(minion_id, pillar, *args, **kwargs)
.UNINDENT
.SS salt.pillar.mongo
@@ -266124,6 +276580,11 @@ neutron: my_openstack_config neutron_networks
.UNINDENT
.INDENT 0.0
.TP
+.B salt.pillar.neutron.__virtual__()
+Only return if python\-neutronclient is installed
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.pillar.neutron.ext_pillar(minion_id, pillar, conf)
Check neutron for all data
.UNINDENT
@@ -266137,6 +276598,22 @@ which contains a list of nodegroups which match for a given minion.
New in version 2016.11.0.
.SS Command Line
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+salt\-call pillar.get nodegroups
+local:
+ \- class_infra
+ \- colo_sj
+ \- state_active
+ \- country_US
+ \- type_saltmaster
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
.SS Configuring Nodegroups Pillar
.INDENT 0.0
.INDENT 3.5
@@ -266495,6 +276972,11 @@ network..interfaces..{{ interface }}..netmask:
For more examples and information see <\fI\%https://github.com/mickep76/pepa\fP>.
.INDENT 0.0
.TP
+.B salt.pillar.pepa.__virtual__()
+Only return if all the modules are available
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.pillar.pepa.ext_pillar(minion_id, pillar, resource, sequence, subkey=False, subkey_only=False)
Evaluate Pepa templates
.UNINDENT
@@ -266648,6 +277130,11 @@ search_order:
.UNINDENT
.INDENT 0.0
.TP
+.B salt.pillar.pillar_ldap.__virtual__()
+Only return if ldap module is installed
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.pillar.pillar_ldap.ext_pillar(minion_id, pillar, config_file)
Execute LDAP searches and return the aggregated data
.UNINDENT
@@ -266825,6 +277312,11 @@ ext_pillar:
.UNINDENT
.INDENT 0.0
.TP
+.B salt.pillar.redismod.__virtual__()
+Only load if the redis module is in __salt__
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.pillar.redismod.ext_pillar(minion_id, pillar, function, **kwargs)
Grabs external pillar data based on configured function
.UNINDENT
@@ -268367,6 +278859,11 @@ ext_pillar:
.UNINDENT
.INDENT 0.0
.TP
+.B salt.pillar.vault.__virtual__()
+This module has no external dependencies
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.pillar.vault.ext_pillar(minion_id, pillar, conf)
Get pillar data from Vault for the configuration \fBconf\fP\&.
.UNINDENT
@@ -268392,6 +278889,11 @@ ext_pillar:
.UNINDENT
.INDENT 0.0
.TP
+.B salt.pillar.venafi.__virtual__()
+No special requirements outside of Salt itself
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.pillar.venafi.ext_pillar(minion_id, pillar, conf)
Return an existing set of certificates
.UNINDENT
@@ -268425,12 +278927,13 @@ configuration, etc. This setup requires only the salt master have access to the
The pillar will return an empty dict if the \(aqos\(aq or \(aqvirtual\(aq grain are not \(aqVMWare\(aq, \(aqESXi\(aq, or \(aqVMWare ESXi\(aq.
.SS Defaults
.INDENT 0.0
-.INDENT 3.5
+.IP \(bu 2
The external pillar will search for Virtual Machines with the VM name matching the minion id.
+.IP \(bu 2
Data will be returned into the \(aqvmware\(aq pillar key.
+.IP \(bu 2
The external pillar has a default set of properties to return for both VirtualMachine and HostSystem types.
.UNINDENT
-.UNINDENT
.SS Configuring the VMWare pillar
.sp
The required minimal configuration in the salt master ext_pillar setup:
@@ -268601,6 +279104,11 @@ part of the pillar regardless of this setting.
.UNINDENT
.INDENT 0.0
.TP
+.B salt.pillar.vmware_pillar.__virtual__()
+Only return if python\-etcd is installed
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.pillar.vmware_pillar.ext_pillar(minion_id, pillar, **kwargs)
Check vmware/vcenter for all data
.UNINDENT
@@ -269095,6 +279603,11 @@ shutdown is a no\-op.
This is a dummy proxy\-minion designed for testing the proxy minion subsystem.
.INDENT 0.0
.TP
+.B salt.proxy.dummy.__virtual__()
+Only return if all the modules are available
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.proxy.dummy.fns()
.UNINDENT
.INDENT 0.0
@@ -269504,6 +280017,11 @@ to find an example structure for Pillar as well as an example \fB\&.sls\fP file
for standing up an ESXi host from scratch.
.INDENT 0.0
.TP
+.B salt.proxy.esxi.__virtual__()
+Only load if the ESXi execution module is available.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.proxy.esxi.ch_config(cmd, *args, **kwargs)
This function is called by the
\fBsalt.modules.esxi.cmd\fP shim.
@@ -269789,6 +280307,11 @@ Look there to find an example structure for pillar as well as an example
\fB\&.sls\fP file for standing up a Dell Chassis from scratch.
.INDENT 0.0
.TP
+.B salt.proxy.fx2.__virtual__()
+Only return if all the modules are available
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.proxy.fx2.admin_password()
Return the admin_password in the DETAILS dictionary, or \(aqcalvin\(aq
(the Dell default) if there is none present
@@ -269924,6 +280447,11 @@ salt\-proxy \-\-proxyid=vmx
.UNINDENT
.INDENT 0.0
.TP
+.B salt.proxy.junos.__virtual__()
+Only return if all the modules are available
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.proxy.junos.init(opts)
Open the connection to the Junos device, login, and bind to the
Resource class
@@ -270183,6 +280711,7 @@ Please check the \fI\%readthedocs\fP page for the updated list of getters.
.TP
.B Returns
A dictionary with three keys:
+.UNINDENT
.INDENT 7.0
.IP \(bu 2
result (True/False): if the operation succeeded
@@ -270191,11 +280720,9 @@ out (object): returns the object as\-is from the call
.IP \(bu 2
comment (string): provides more details in case the call failed
.IP \(bu 2
-traceback (string): complete traceback in case of exception. Please submit an issue including this traceback
-.UNINDENT
-.sp
-on the \fI\%correct driver repo\fP and make sure to read the \fI\%FAQ\fP
-
+traceback (string): complete traceback in case of exception. Please
+submit an issue including this traceback on the \fI\%correct driver repo\fP
+and make sure to read the \fI\%FAQ\fP
.UNINDENT
.sp
Example:
@@ -270310,6 +280837,11 @@ The functions from the proxy minion can be run from the salt commandline using
the \fBsalt.modules.nxos\fP execution module.
.INDENT 0.0
.TP
+.B salt.proxy.nxos.__virtual__()
+Only return if all the modules are available
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.proxy.nxos.add_config(lines)
Add one or more config lines to the switch running config
.INDENT 7.0
@@ -270575,6 +281107,11 @@ Constants for the lamp operations.
.UNINDENT
.INDENT 0.0
.TP
+.B salt.proxy.philips_hue.__virtual__()
+Validate the module.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.proxy.philips_hue.call_alert(*args, **kwargs)
Lamp alert
.sp
@@ -270671,7 +281208,7 @@ Options:
.IP \(bu 2
.INDENT 2.0
.TP
-\fBcolor\fP: Fixed color. Values are: red, green, blue, orange, pink, white,
+.B \fBcolor\fP: Fixed color. Values are: red, green, blue, orange, pink, white,
yellow, daylight, purple. Default white.
.UNINDENT
.IP \(bu 2
@@ -270683,7 +281220,7 @@ Advanced:
.IP \(bu 2
.INDENT 2.0
.TP
-\fBgamut\fP: XY coordinates. Use gamut according to the Philips HUE devices documentation.
+.B \fBgamut\fP: XY coordinates. Use gamut according to the Philips HUE devices documentation.
More: \fI\%http://www.developers.meethue.com/documentation/hue\-xy\-values\fP
.UNINDENT
.UNINDENT
@@ -270904,6 +281441,11 @@ This is a simple proxy\-minion designed to connect to and communicate with
the bottle\-based web service contained in \fI\%https://github.com/saltstack/salt\-contrib/tree/master/proxyminion_rest_example\fP
.INDENT 0.0
.TP
+.B salt.proxy.rest_sample.__virtual__()
+Only return if all the modules are available
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.proxy.rest_sample.grains()
Get the grains from the proxied device
.UNINDENT
@@ -271000,6 +281542,11 @@ This can be used as an option when the device does not provide
an api over HTTP and doesn\(aqt have the python stack to run a minion.
.INDENT 0.0
.TP
+.B salt.proxy.ssh_sample.__virtual__()
+Only return if all the modules are available
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.proxy.ssh_sample.grains()
Get the grains from the proxied device
.UNINDENT
@@ -271279,7 +281826,7 @@ _
T{
\fBcache\fP
T} T{
-The \fIcache\fP roster provides a flexible interface to the Salt Masters\(aq minion cache to access regular minions over \fBsalt\-ssh\fP\&.
+The \fBcache\fP roster provides a flexible interface to the Salt Masters\(aq minion cache to access regular minions over \fBsalt\-ssh\fP\&.
T}
_
T{
@@ -271443,7 +281990,7 @@ Default: /etc/salt/roster
.UNINDENT
.SS salt.roster.cache
.sp
-The \fIcache\fP roster provides a flexible interface to the Salt Masters\(aq minion cache
+The \fBcache\fP roster provides a flexible interface to the Salt Masters\(aq minion cache
to access regular minions over \fBsalt\-ssh\fP\&.
.sp
.INDENT 0.0
@@ -271493,32 +282040,16 @@ You can define lists of parameters as well, the first result from the list will
.sp
.nf
.ft C
-
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
# default
roster_order:
-.INDENT 0.0
-.INDENT 3.5
-.INDENT 0.0
-.TP
-.B host:
-.INDENT 7.0
-.IP \(bu 2
-ipv6\-private # IPv6 addresses in private ranges
-.IP \(bu 2
-ipv6\-global # IPv6 addresses in global ranges
-.IP \(bu 2
-ipv4\-private # IPv4 addresses in private ranges
-.IP \(bu 2
-ipv4\-public # IPv4 addresses in public ranges
-.IP \(bu 2
-ipv4\-local # loopback addresses
-.UNINDENT
-.UNINDENT
+ host:
+ \- ipv6\-private # IPv6 addresses in private ranges
+ \- ipv6\-global # IPv6 addresses in global ranges
+ \- ipv4\-private # IPv4 addresses in private ranges
+ \- ipv4\-public # IPv4 addresses in public ranges
+ \- ipv4\-local # loopback addresses
+.ft P
+.fi
.UNINDENT
.UNINDENT
.sp
@@ -271532,25 +282063,14 @@ Other address selection parameters are also possible:
.sp
.nf
.ft C
-
+roster_order:
+ host:
+ \- global|public|private|local # Both IPv6 and IPv4 addresses in that range
+ \- 2000::/3 # CIDR networks, both IPv4 and IPv6 are supported
.ft P
.fi
.UNINDENT
.UNINDENT
-.INDENT 0.0
-.TP
-.B roster_order:
-.INDENT 7.0
-.TP
-.B host:
-.INDENT 7.0
-.IP \(bu 2
-global|public|private|local # Both IPv6 and IPv4 addresses in that range
-.IP \(bu 2
-2000::/3 # CIDR networks, both IPv4 and IPv6 are supported
-.UNINDENT
-.UNINDENT
-.UNINDENT
.SS Using cached data
.sp
Several cached libraries can be selected using the \fBlibrary: \(ga\(ga prefix, followed by the library key.
@@ -271563,54 +282083,27 @@ This should be especially useful for the other roster keys:
.sp
.nf
.ft C
+roster_order:
+ host:
+ \- grain: fqdn_ip4 # Lookup this grain
+ \- mine: network.ip_addrs # Mine data lookup works the same
+ password: sdb://vault/ssh_pass # Salt SDB URLs are also supported
+
+ user:
+ \- pillar: ssh:auth:user # Lookup this pillar key
+ \- sdb://osenv/USER # Lookup this env var through sdb
+
+ priv:
+ \- pillar: # Lists are also supported
+ \- salt:ssh:private_key
+ \- ssh:auth:private_key
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
-.B roster_order:
-.INDENT 7.0
-.TP
-.B host:
-.INDENT 7.0
-.IP \(bu 2
-grain: fqdn_ip4 # Lookup this grain
-.IP \(bu 2
-mine: network.ip_addrs # Mine data lookup works the same
-.UNINDENT
-.UNINDENT
-.sp
-password: sdb://vault/ssh_pass # Salt SDB URLs are also supported
-.INDENT 7.0
-.TP
-.B user:
-.INDENT 7.0
-.IP \(bu 2
-pillar: \fI\%ssh:auth:user\fP # Lookup this pillar key
-.IP \(bu 2
-sdb://osenv/USER # Lookup this env var through sdb
-.UNINDENT
-.TP
-.B priv:
-.INDENT 7.0
-.IP \(bu 2
-.INDENT 2.0
-.TP
-.B pillar: # Lists are also supported
-.INDENT 7.0
-.IP \(bu 2
-salt:ssh:private_key
-.IP \(bu 2
-\fI\%ssh:auth:private_key\fP
-.UNINDENT
-.UNINDENT
-.UNINDENT
-.UNINDENT
-.UNINDENT
-.INDENT 0.0
-.TP
.B salt.roster.cache.targets(tgt, tgt_type=\(aqglob\(aq, **kwargs)
Return the targets from the Salt Masters\(aq minion cache.
All targets and matchers are supported.
@@ -272093,6 +282586,12 @@ is not using the defaults. Default is \fBprotocol: https\fP and \fBport: 3451\fP
.UNINDENT
.INDENT 0.0
.TP
+.B salt.runners.asam.__virtual__()
+Check for ASAM Fan\-Out driver configuration in master config file
+or directory and load runner only if it is specified
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.runners.asam.add_platform(name, platform_set, server_url)
To add an ASAM platform using the specified ASAM platform set on the Novell
Fan\-Out Driver
@@ -272301,21 +282800,21 @@ Special fields:
.IP \(bu 2
\fBvrf\fP: return the name of the VRF.
.IP \(bu 2
-\fBconnection_stats\fP: returning an output of the form
-.UNINDENT
-.sp
-\fB///\fP, e.g.
-\fBEstablished 398/399/399/0\fP similar to the usual output
-from network devices.
-\- \fBinterface_description\fP: matches the neighbor details with the
+\fBconnection_stats\fP: returning an output of the form \fB
+///\fP, e.g. \fBEstablished
+398/399/399/0\fP similar to the usual output from network devices.
+.IP \(bu 2
+\fBinterface_description\fP: matches the neighbor details with the
corresponding interface and returns its description. This will reuse
-functionality from the \fBnet runner\fP,
-so the user needs to enable the mines as specified in the documentation.
-\- \fBinterface_name\fP: matches the neighbor details with the
-corresponding interface and returns the name.
-Similar to \fBinterface_description\fP, this will reuse
-functionality from the \fBnet runner\fP,
-so the user needs to enable the mines as specified in the documentation.
+functionality from the \fBnet runner\fP, so the user needs to enable the mines
+as specified in the documentation.
+.IP \(bu 2
+\fBinterface_name\fP: matches the neighbor details with the
+corresponding interface and returns the name. Similar to
+\fBinterface_description\fP, this will reuse functionality from the
+\fBnet runner\fP, so the user needs to
+enable the mines as specified in the documentation.
+.UNINDENT
.TP
.B display: \fBTrue\fP
Display on the screen or return structured object? Default: \fBTrue\fP (return on the CLI).
@@ -272357,11 +282856,7 @@ Search for BGP neighbors details in the mines of the \fBbgp.neighbors\fP functio
Arguments:
.INDENT 7.0
.TP
-.B
-.nf
-*
-.fi
-asns
+.B asns
A list of AS numbers to search for.
The runner will return only the neighbors of these AS numbers.
.TP
@@ -272491,14 +282986,10 @@ will remove the lock from all github.com remotes.
.B type
update,checkout
The types of lock to clear. Can be \fBupdate\fP, \fBcheckout\fP, or both of
-.UNINDENT
+them (either comma\-separated or as a Python list).
.sp
-et (either comma\-separated or as a Python list).
-.INDENT 7.0
-.INDENT 3.5
New in version 2015.8.8.
-.UNINDENT
.UNINDENT
.sp
CLI Example:
@@ -272874,6 +283365,12 @@ Nitin Madhok <\fI\%nmadhok@clemson.edu\fP>
.UNINDENT
.INDENT 0.0
.TP
+.B salt.runners.ddns.__virtual__()
+Check if required libs (python\-dns) is installed and load runner
+only if they are present
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.runners.ddns.add_host(zone, name, ttl, ip, keyname, keyfile, nameserver, timeout, port=53, keyalgorithm=\(aqhmac\-md5\(aq)
Create both A and PTR (reverse) records for a host.
.sp
@@ -273016,6 +283513,11 @@ This API currently only supports RSA key types. Support for other key types wil
if interest warrants.
.INDENT 0.0
.TP
+.B salt.runners.digicertapi.__virtual__()
+Only load the module if digicert has configuration in place
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.runners.digicertapi.del_cached_domain(domains)
Delete cached domains from the master
.sp
@@ -273286,6 +283788,11 @@ A runner module to collect and display the inline documentation from the
various module types
.INDENT 0.0
.TP
+.B salt.runners.doc.__virtual__()
+Always load
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.runners.doc.execution()
Collect all the sys.doc output from each minion and return the aggregate
.sp
@@ -274313,10 +284820,14 @@ The external job cache to use. Default: \fINone\fP\&.
.UNINDENT
.sp
CLI Example:
-.. code\-block:: bash
.INDENT 7.0
.INDENT 3.5
+.sp
+.nf
+.ft C
salt\-run jobs.exit_success 20160520145827701627
+.ft P
+.fi
.UNINDENT
.UNINDENT
.UNINDENT
@@ -275709,6 +286220,12 @@ mattermost:
.UNINDENT
.INDENT 0.0
.TP
+.B salt.runners.mattermost.__virtual__()
+Return virtual name of the module.
+:return: The virtual name of the module.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.runners.mattermost.post_event(event, channel=None, username=None, api_url=None, hook=None)
Send an event to a Mattermost channel.
:param channel: The channel name, either will work.
@@ -275728,11 +286245,16 @@ Send a message to a Mattermost channel.
:param api_url: The Mattermost api url, if not specified in the configuration.
:param hook: The Mattermost hook, if not specified in the configuration.
:return: Boolean if message was sent successfully.
+.sp
CLI Example:
-.. code\-block:: bash
.INDENT 7.0
.INDENT 3.5
+.sp
+.nf
+.ft C
salt\-run mattermost.post_message message=\(aqBuild is done\(aq
+.ft P
+.fi
.UNINDENT
.UNINDENT
.UNINDENT
@@ -276017,11 +286539,7 @@ Return only the best match with the interfaces IP networks
when the saerching pattern is a valid IP Address or Network.
.TP
.B display: \fBTrue\fP
-Display on the screen or return structured object? Default:
-.nf
-\(ga\(ga
-.fi
-True\(ga\(ga(return on the CLI).
+Display on the screen or return structured object? Default: \fBTrue\fP (return on the CLI).
.UNINDENT
.sp
CLI Example:
@@ -276466,6 +286984,11 @@ my\-pagerduty\-account:
.UNINDENT
.INDENT 0.0
.TP
+.B salt.runners.pagerduty.__virtual__()
+No dependencies outside of what Salt itself requires
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.runners.pagerduty.create_event(service_key=None, description=None, details=None, incident_key=None, profile=None)
Create an event in PagerDuty. Designed for use in states.
.sp
@@ -277005,6 +287528,33 @@ salt\-run queue.process_runner 5
.SS salt.runners.reactor
.sp
A convenience system to manage reactors
+.sp
+Beginning in the 2017.7 release, the reactor runner requires that the reactor
+system is running. This is accomplished one of two ways, either
+by having reactors configured or by including \fBreactor\fP in the
+engine configuration for the Salt master.
+.INDENT 0.0
+.INDENT 3.5
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.INDENT 0.0
+.TP
+.B engines:
+.INDENT 7.0
+.IP \(bu 2
+reactor
+.UNINDENT
+.UNINDENT
+.UNINDENT
+.UNINDENT
.INDENT 0.0
.TP
.B salt.runners.reactor.add(event, reactors, saltenv=\(aqbase\(aq, test=None)
@@ -277886,6 +288436,11 @@ salt \(aq*\(aq sdb.set sdb://mymemcached/foo bar
Runner for SmartOS minions control vmadm
.INDENT 0.0
.TP
+.B salt.runners.smartos_vmadm.__virtual__()
+Provides vmadm runner
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.runners.smartos_vmadm.get(search, one=True)
Return information for vms
.INDENT 7.0
@@ -278192,6 +288747,12 @@ not using the defaults. Default is \fBprotocol: https\fP\&.
.UNINDENT
.INDENT 0.0
.TP
+.B salt.runners.spacewalk.__virtual__()
+Check for spacewalk configuration in master config file
+or directory and load runner only if it is specified
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.runners.spacewalk.addGroupsToKey(server, activation_key, groups)
Add server groups to a activation key
.sp
@@ -278802,6 +289363,11 @@ venafi:
.UNINDENT
.INDENT 0.0
.TP
+.B salt.runners.venafiapi.__virtual__()
+Only load the module if venafi is installed
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.runners.venafiapi.del_cached_domain(domains)
Delete cached domains from the master
.sp
@@ -279108,7 +289674,7 @@ Return information about the host connected to this master
.UNINDENT
.INDENT 0.0
.TP
-.B salt.runners.virt.init(name, cpu, mem, image, hypervisor=\(aqkvm\(aq, host=None, seed=True, nic=\(aqdefault\(aq, install=True, start=True, disk=\(aqdefault\(aq, saltenv=\(aqbase\(aq, enable_vnc=False)
+.B salt.runners.virt.init(name, cpu, mem, image, hypervisor=\(aqkvm\(aq, host=None, seed=True, nic=\(aqdefault\(aq, install=True, start=True, disk=\(aqdefault\(aq, saltenv=\(aqbase\(aq, enable_vnc=False, seed_cmd=\(aqseed.apply\(aq, enable_qcow=False)
This routine is used to create a new virtual machine. This routines takes
a number of options to determine what the newly created virtual machine
will look like.
@@ -279130,14 +289696,14 @@ The network location of the virtual machine image, commonly a location
on the salt fileserver, but http, https and ftp can also be used.
.TP
.B hypervisor
-The hypervisor to use for the new virtual machine. Default is \(aqkvm\(aq.
+The hypervisor to use for the new virtual machine. Default is \fIkvm\fP\&.
.TP
.B host
The host to use for the new virtual machine, if this is omitted
Salt will automatically detect what host to use.
.TP
.B seed
-Set to False to prevent Salt from seeding the new virtual machine.
+Set to \fIFalse\fP to prevent Salt from seeding the new virtual machine.
.TP
.B nic
The nic profile to use, defaults to the "default" nic profile which
@@ -279153,6 +289719,17 @@ The disk profile to use
.TP
.B saltenv
The Salt environment to use
+.TP
+.B enable_vnc
+Whether a VNC screen is attached to resulting VM. Default is \fIFalse\fP\&.
+.TP
+.B seed_cmd
+If seed is \fITrue\fP, use this execution module function to seed new VM.
+Default is \fIseed.apply\fP\&.
+.TP
+.B enable_qcow
+Clone disk image as a copy\-on\-write qcow2 image, using downloaded
+\fIimage\fP as backing file.
.UNINDENT
.UNINDENT
.INDENT 0.0
@@ -279243,6 +289820,11 @@ vistara:
.UNINDENT
.INDENT 0.0
.TP
+.B salt.runners.vistara.__virtual__()
+Check to see if master config has the necessary config
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.runners.vistara.delete_device(name, safety_on=True)
Deletes a device from Vistara based on DNS name or partial name. By default,
delete_device will only perform the delete if a single host is returned. Set
@@ -279496,6 +290078,11 @@ master_ip: sdb://mastercloudcache/public_ips?bank=cloud/active/ec2/my\-ec2\-conf
.UNINDENT
.INDENT 0.0
.TP
+.B salt.sdb.cache.__virtual__()
+Only load the module if keyring is installed
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.sdb.cache.delete(key, service=None, profile=None)
Get a value from the cache service
.UNINDENT
@@ -279552,6 +290139,11 @@ confidant\-common, confidant\-client
.SS Module Documentation
.INDENT 0.0
.TP
+.B salt.sdb.confidant.__virtual__()
+Only return if requests and boto are installed.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.sdb.confidant.get(key, profile=None)
Read pillar data from Confidant via its API.
.sp
@@ -279590,6 +290182,24 @@ This module allows access to Consul using an \fBsdb://\fP URI
Like all sdb modules, the Consul module requires a configuration profile to
be configured in either the minion or master configuration file. This profile
requires very little. For example:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+myconsul:
+ driver: consul
+ host: 127.0.0.1
+ port: 8500
+ token: b6376760\-a8bb\-edd5\-fcda\-33bc13bfc556
+ scheme: http
+ consistency: default
+ dc: dev
+ verify: True
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
.sp
The \fBdriver\fP refers to the Consul module, all other options are optional.
For option details see: \fI\%https://python\-consul.readthedocs.io/en/latest/#consul\fP
@@ -279657,6 +290267,11 @@ Additional contributions to build true map\-reduce functionality into this modul
would be welcome.
.INDENT 0.0
.TP
+.B salt.sdb.couchdb.__virtual__()
+Require the python2\-couchdb libraries
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.sdb.couchdb.get(key, profile=None)
Get a value from couchdb by id
.UNINDENT
@@ -279750,6 +290365,11 @@ my\-openstack\-config:
.UNINDENT
.INDENT 0.0
.TP
+.B salt.sdb.env.__virtual__()
+Always load
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.sdb.env.get(key, profile=None)
Get a value
.UNINDENT
@@ -279813,6 +290433,11 @@ password: sdb://myetcd/mypassword
.UNINDENT
.INDENT 0.0
.TP
+.B salt.sdb.etcd_db.__virtual__()
+Only load the module if keyring is installed
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.sdb.etcd_db.delete(key, service=None, profile=None)
Get a value from the etcd service
.UNINDENT
@@ -279893,6 +290518,11 @@ examples and documentation, see keyring:
.sp
New in version 2014.1.4.
+.INDENT 0.0
+.TP
+.B salt.sdb.keyring_db.__virtual__()
+Only load the module if keyring is installed
+.UNINDENT
.INDENT 0.0
.TP
.B salt.sdb.keyring_db.get(key, service=None, profile=None)
@@ -279956,6 +290586,11 @@ password: sdb://mymemcached/mykey
.UNINDENT
.INDENT 0.0
.TP
+.B salt.sdb.memcached.__virtual__()
+Only load the module if memcached is installed
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.sdb.memcached.get(key, profile=None)
Get a value from memcached
.UNINDENT
@@ -280127,6 +290762,11 @@ Instead of a table name, it is possible to provide custom SQL statements to
create the table(s) and get and set values.
.INDENT 0.0
.TP
+.B salt.sdb.sqlite3.__virtual__()
+Only load if sqlite3 is available.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.sdb.sqlite3.get(key, profile=None)
Get a value from sqlite3
.UNINDENT
@@ -280183,6 +290823,11 @@ tism:
.UNINDENT
.INDENT 0.0
.TP
+.B salt.sdb.tism.__virtual__()
+This module has no other system dependencies
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.sdb.tism.get(key, service=None, profile=None)
Get a decrypted secret from the tISMd API
.UNINDENT
@@ -281659,7 +292304,7 @@ _
T{
\fBmsteams\fP
T} T{
-Send a message card to Microsoft Teams ======================= This state is useful for sending messages to Teams during state runs.
+Send a message card to Microsoft Teams
T}
_
T{
@@ -282025,6 +292670,7 @@ _
T{
\fBreg\fP
T} T{
+Manage the Windows registry =========================== Many python developers think of registry keys as if they were python keys in a dictionary which is not the case.
T}
_
T{
@@ -282503,7 +293149,12 @@ dev.example.com:
.UNINDENT
.INDENT 0.0
.TP
-.B salt.states.acme.cert(name, aliases=None, email=None, webroot=None, test_cert=False, renew=None, keysize=None, server=None, owner=\(aqroot\(aq, group=\(aqroot\(aq, certname=None)
+.B salt.states.acme.__virtual__()
+Only work when the ACME module agrees
+.UNINDENT
+.INDENT 0.0
+.TP
+.B salt.states.acme.cert(name, aliases=None, email=None, webroot=None, test_cert=False, renew=None, keysize=None, server=None, owner=\(aqroot\(aq, group=\(aqroot\(aq, mode=\(aq0640\(aq, certname=None)
Obtain/renew a certificate from an ACME CA, probably Let\(aqs Encrypt.
.INDENT 7.0
.TP
@@ -282526,9 +293177,11 @@ Obtain/renew a certificate from an ACME CA, probably Let\(aqs Encrypt.
.IP \(bu 2
\fBserver\fP \-\- API endpoint to talk to
.IP \(bu 2
-\fBowner\fP \-\- owner of private key
+\fBowner\fP \-\- owner of the private key file
.IP \(bu 2
-\fBgroup\fP \-\- group of private key
+\fBgroup\fP \-\- group of the private key file
+.IP \(bu 2
+\fBmode\fP \-\- mode of the private key file
.IP \(bu 2
\fBcertname\fP \-\- Name of the certificate to save
.UNINDENT
@@ -282638,6 +293291,11 @@ hadoop\-0.20\-conf:
.UNINDENT
.INDENT 0.0
.TP
+.B salt.states.alternatives.__virtual__()
+Only load if alternatives execution module is available.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.alternatives.auto(name)
New in version 0.17.0.
@@ -282781,6 +293439,11 @@ Disable security conf:
.UNINDENT
.INDENT 0.0
.TP
+.B salt.states.apache_conf.__virtual__()
+Only load if a2enconf is available.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.apache_conf.disabled(name)
Ensure an Apache conf is disabled.
.INDENT 7.0
@@ -282825,6 +293488,11 @@ Disable cgi module:
.UNINDENT
.INDENT 0.0
.TP
+.B salt.states.apache_module.__virtual__()
+Only load if a2enmod is available.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.apache_module.disabled(name)
Ensure an Apache module is disabled.
.sp
@@ -282875,6 +293543,11 @@ Disable default site:
.UNINDENT
.INDENT 0.0
.TP
+.B salt.states.apache_site.__virtual__()
+Only load if a2ensite is available.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.apache_site.disabled(name)
Ensure an Apache site is disabled.
.INDENT 7.0
@@ -282897,6 +293570,11 @@ Name of the Apache site
.SS Package management operations specific to APT\- and DEB\-based systems
.INDENT 0.0
.TP
+.B salt.states.aptpkg.__virtual__()
+Only work on apt\-based platforms with pkg.get_selections
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.aptpkg.held(name)
Set package in \(aqhold\(aq state, meaning it will not be upgraded.
.INDENT 7.0
@@ -283644,6 +294322,11 @@ jboss_module_downloaded:
The at state can be add disposable regularly scheduled tasks for your system.
.INDENT 0.0
.TP
+.B salt.states.at.__virtual__()
+Most everything has the ability to support at(1)
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.at.absent(name, jobid=None, **kwargs)
Changed in version 2017.7.0.
@@ -283662,12 +294345,7 @@ Job\(aqs tag
string
Runs user\-specified jobs
.TP
-.B
-.nf
-**
-.fi
-kwags
-*
+.B kwargs
Addition kwargs can be provided to filter jobs.
See output of \fIat.jobcheck\fP for more.
.UNINDENT
@@ -284080,6 +294758,11 @@ myqueue:
.UNINDENT
.INDENT 0.0
.TP
+.B salt.states.aws_sqs.__virtual__()
+Only load if aws is available.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.aws_sqs.absent(name, region, user=None, opts=False)
Remove the named SQS queue if it exists.
.INDENT 7.0
@@ -284205,6 +294888,11 @@ f5_bigip_11.6
.UNINDENT
.INDENT 0.0
.TP
+.B salt.states.bigip.__virtual__()
+Only load if the bigip exec module is available in __salt__
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.bigip.add_pool_member(hostname, username, password, name, member)
A function to connect to a bigip device and add a new member to an existing pool.
.INDENT 7.0
@@ -285605,6 +296293,11 @@ master\-data:
.sp
New in version 2014.7.0.
+.INDENT 0.0
+.TP
+.B salt.states.blockdev.__virtual__()
+Only load this module if the disk execution module is available
+.UNINDENT
.INDENT 0.0
.TP
.B salt.states.blockdev.formatted(name, fs_type=\(aqext4\(aq, force=False, **kwargs)
@@ -285724,97 +296417,69 @@ myprofile:
.fi
.UNINDENT
.UNINDENT
-.sp
-XXX FIXME
-.. code\-block:: yaml
.INDENT 0.0
.INDENT 3.5
-.INDENT 0.0
-.TP
-.B Ensure myelasticache exists:
-.INDENT 7.0
-.TP
-.B boto3_elasticache.present:
-.INDENT 7.0
-.IP \(bu 2
-name: myelasticache
-.IP \(bu 2
-engine: redis
-.IP \(bu 2
-cache_node_type: cache.t1.micro
-.IP \(bu 2
-num_cache_nodes: 1
-.IP \(bu 2
-notification_topic_arn: arn:aws:sns:us\-east\-1:879879:my\-sns\-topic
-.IP \(bu 2
-region: us\-east\-1
-.IP \(bu 2
-keyid: GKTADJGHEIQSXMKKRBJ08H
-.IP \(bu 2
-key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs
-.UNINDENT
-.UNINDENT
-.UNINDENT
.sp
+.nf
+.ft C
+Ensure myelasticache exists:
+ boto3_elasticache.present:
+ \- name: myelasticache
+ \- engine: redis
+ \- cache_node_type: cache.t1.micro
+ \- num_cache_nodes: 1
+ \- notification_topic_arn: arn:aws:sns:us\-east\-1:879879:my\-sns\-topic
+ \- region: us\-east\-1
+ \- keyid: GKTADJGHEIQSXMKKRBJ08H
+ \- key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
# Using a profile from pillars
Ensure myelasticache exists:
+ boto3_elasticache.present:
+ \- name: myelasticache
+ \- engine: redis
+ \- cache_node_type: cache.t1.micro
+ \- num_cache_nodes: 1
+ \- notification_topic_arn: arn:aws:sns:us\-east\-1:879879:my\-sns\-topic
+ \- region: us\-east\-1
+ \- profile: myprofile
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
.INDENT 0.0
.INDENT 3.5
-.INDENT 0.0
-.TP
-.B boto3_elasticache.present:
-.INDENT 7.0
-.IP \(bu 2
-name: myelasticache
-.IP \(bu 2
-engine: redis
-.IP \(bu 2
-cache_node_type: cache.t1.micro
-.IP \(bu 2
-num_cache_nodes: 1
-.IP \(bu 2
-notification_topic_arn: arn:aws:sns:us\-east\-1:879879:my\-sns\-topic
-.IP \(bu 2
-region: us\-east\-1
-.IP \(bu 2
-profile: myprofile
-.UNINDENT
-.UNINDENT
-.UNINDENT
-.UNINDENT
.sp
+.nf
+.ft C
# Passing in a profile
Ensure myelasticache exists:
-.INDENT 0.0
-.INDENT 3.5
+ boto3_elasticache.present:
+ \- name: myelasticache
+ \- engine: redis
+ \- cache_node_type: cache.t1.micro
+ \- num_cache_nodes: 1
+ \- notification_topic_arn: arn:aws:sns:us\-east\-1:879879:my\-sns\-topic
+ \- region: us\-east\-1
+ \- profile:
+ keyid: GKTADJGHEIQSXMKKRBJ08H
+ key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
.INDENT 0.0
.TP
-.B boto3_elasticache.present:
-.INDENT 7.0
-.IP \(bu 2
-name: myelasticache
-.IP \(bu 2
-engine: redis
-.IP \(bu 2
-cache_node_type: cache.t1.micro
-.IP \(bu 2
-num_cache_nodes: 1
-.IP \(bu 2
-notification_topic_arn: arn:aws:sns:us\-east\-1:879879:my\-sns\-topic
-.IP \(bu 2
-region: us\-east\-1
-.IP \(bu 2
-.INDENT 2.0
-.TP
-.B profile:
-keyid: GKTADJGHEIQSXMKKRBJ08H
-key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs
-.UNINDENT
-.UNINDENT
-.UNINDENT
-.UNINDENT
-.UNINDENT
-.UNINDENT
+.B salt.states.boto3_elasticache.__virtual__()
+Only load if boto is available.
.UNINDENT
.INDENT 0.0
.TP
@@ -285873,25 +296538,36 @@ dependent resources.
.TP
.B security_groups
One or more VPC security groups (names and/or IDs) associated with the cache cluster.
-Note: This is additive with any sec groups provided via the SecurityGroupIds parameter
+.sp
+\fBNOTE:\fP
.INDENT 7.0
.INDENT 3.5
-below. Use this parameter ONLY when you are creating a cluster in a VPC.
+This is additive with any sec groups provided via the
+SecurityGroupIds parameter below. Use this parameter ONLY when you
+are creating a cluster in a VPC.
.UNINDENT
.UNINDENT
.TP
.B CacheClusterId
The node group (shard) identifier. This parameter is stored as a lowercase string.
+.sp
Constraints:
.INDENT 7.0
-.INDENT 3.5
+.IP \(bu 2
A name must contain from 1 to 20 alphanumeric characters or hyphens.
+.IP \(bu 2
The first character must be a letter.
+.IP \(bu 2
A name cannot end with a hyphen or contain two consecutive hyphens.
.UNINDENT
-.UNINDENT
.sp
-Note: In general this parameter is not needed, as \(aqname\(aq is used if it\(aqs not provided.
+\fBNOTE:\fP
+.INDENT 7.0
+.INDENT 3.5
+In general this parameter is not needed, as \(aqname\(aq is used if it\(aqs
+not provided.
+.UNINDENT
+.UNINDENT
.TP
.B ReplicationGroupId
The ID of the replication group to which this cache cluster should belong. If this
@@ -285901,27 +296577,26 @@ is not part of any replication group. If the specified replication group is
Multi\-AZ enabled and the Availability Zone is not specified, the cache cluster is
created in Availability Zones that provide the best spread of read replicas across
Availability Zones.
-Notes: This parameter is ONLY valid if the Engine parameter is redis.
-.INDENT 7.0
-.INDENT 3.5
-Due to current limitations on Redis (cluster mode disabled), this parameter
-.UNINDENT
-.UNINDENT
-.sp
-is not supported on Redis (cluster mode enabled) replication groups.
.TP
.B AZMode
Specifies whether the nodes in this Memcached cluster are created in a single
Availability Zone or created across multiple Availability Zones in the cluster\(aqs
-region. If the AZMode and PreferredAvailabilityZones are not specified,
+region. If the AZMode and PreferredAvailabilityZones are not specified,
ElastiCache assumes single\-az mode.
-Note: This parameter is ONLY supported for Memcached cache clusters.
+.sp
+\fBNOTE:\fP
+.INDENT 7.0
+.INDENT 3.5
+This parameter is ONLY supported for Memcached cache clusters.
+.UNINDENT
+.UNINDENT
.TP
.B PreferredAvailabilityZone
The EC2 Availability Zone in which the cache cluster is created. All nodes
belonging to this Memcached cache cluster are placed in the preferred Availability
Zone. If you want to create your nodes across multiple Availability Zones, use
PreferredAvailabilityZones.
+.sp
Default: System chosen Availability Zone.
.TP
.B PreferredAvailabilityZones
@@ -285930,22 +296605,28 @@ the zones in the list is not important. The number of Availability Zones listed
must equal the value of NumCacheNodes. If you want all the nodes in the same
Availability Zone, use PreferredAvailabilityZone instead, or repeat the
Availability Zone multiple times in the list.
-Note: This option is ONLY supported on Memcached.
-Note: If you are creating your cache cluster in an Amazon VPC (recommended) you
-.INDENT 7.0
-.INDENT 3.5
-can only locate nodes in Availability Zones that are associated with the
-subnets in the selected subnet group.
-.UNINDENT
-.UNINDENT
.sp
Default: System chosen Availability Zones.
+.sp
+\fBNOTE:\fP
+.INDENT 7.0
+.INDENT 3.5
+This option is ONLY supported on Memcached.
+.sp
+If you are creating your cache cluster in an Amazon VPC
+(recommended) you can only locate nodes in Availability Zones that
+are associated with the subnets in the selected subnet group.
+.UNINDENT
+.UNINDENT
.TP
.B NumCacheNodes
The initial (integer) number of cache nodes that the cache cluster has.
-Notes: For clusters running Redis, this value must be 1.
+.sp
+\fBNOTE:\fP
.INDENT 7.0
.INDENT 3.5
+For clusters running Redis, this value must be 1.
+.sp
For clusters running Memcached, this value must be between 1 and 20.
.UNINDENT
.UNINDENT
@@ -285954,14 +296635,22 @@ For clusters running Memcached, this value must be between 1 and 20.
The compute and memory capacity of the nodes in the node group (shard).
Valid node types (and pricing for them) are exhaustively described at
\fI\%https://aws.amazon.com/elasticache/pricing/\fP
-Notes: All T2 instances must be created in a VPC
+.sp
+\fBNOTE:\fP
.INDENT 7.0
.INDENT 3.5
-Redis backup/restore is not supported for Redis (cluster mode disabled)
-T1 and T2 instances. Backup/restore is supported on Redis (cluster mode
-enabled) T2 instances.
-Redis Append\-only files (AOF) functionality is not supported for T1 or
-T2 instances.
+.INDENT 0.0
+.INDENT 3.5
+All T2 instances must be created in a VPC
+.UNINDENT
+.UNINDENT
+.sp
+Redis backup/restore is not supported for Redis (cluster mode
+disabled) T1 and T2 instances. Backup/restore is supported on Redis
+(cluster mode enabled) T2 instances.
+.sp
+Redis Append\-only files (AOF) functionality is not supported for T1
+or T2 instances.
.UNINDENT
.UNINDENT
.TP
@@ -285972,12 +296661,14 @@ this parameter are: memcached | redis
.B EngineVersion
The version number of the cache engine to be used for this cache cluster. To view
the supported cache engine versions, use the DescribeCacheEngineVersions operation.
-Note: You can upgrade to a newer engine version but you cannot downgrade to an
+.sp
+\fBNOTE:\fP
.INDENT 7.0
.INDENT 3.5
-earlier engine version. If you want to use an earlier engine version, you
-must delete the existing cache cluster or replication group and create it
-anew with the earlier engine version.
+You can upgrade to a newer engine version but you cannot downgrade
+to an earlier engine version. If you want to use an earlier engine
+version, you must delete the existing cache cluster or replication
+group and create it anew with the earlier engine version.
.UNINDENT
.UNINDENT
.TP
@@ -285991,8 +296682,13 @@ a cluster.
The name of the Cache Subnet Group to be used for the cache cluster. Use this
parameter ONLY when you are creating a cache cluster within a VPC.
.sp
-Note: If you\(aqre going to launch your cluster in an Amazon VPC, you need to create
-a subnet group before you start creating a cluster.
+\fBNOTE:\fP
+.INDENT 7.0
+.INDENT 3.5
+If you\(aqre going to launch your cluster in an Amazon VPC, you need
+to create a subnet group before you start creating a cluster.
+.UNINDENT
+.UNINDENT
.TP
.B CacheSecurityGroupNames
A list of Cache Security Group names to associate with this cache cluster. Use
@@ -286012,29 +296708,50 @@ A single\-element string list containing an Amazon Resource Name (ARN) that
uniquely identifies a Redis RDB snapshot file stored in Amazon S3. The snapshot
file is used to populate the node group (shard). The Amazon S3 object name in
the ARN cannot contain any commas.
-Note: This parameter is ONLY valid if the Engine parameter is redis.
+.sp
+\fBNOTE:\fP
+.INDENT 7.0
+.INDENT 3.5
+This parameter is ONLY valid if the Engine parameter is redis.
+.UNINDENT
+.UNINDENT
.TP
.B SnapshotName
The name of a Redis snapshot from which to restore data into the new node group
(shard). The snapshot status changes to restoring while the new node group (shard)
is being created.
-Note: This parameter is ONLY valid if the Engine parameter is redis.
+.sp
+\fBNOTE:\fP
+.INDENT 7.0
+.INDENT 3.5
+This parameter is ONLY valid if the Engine parameter is redis.
+.UNINDENT
+.UNINDENT
.TP
.B PreferredMaintenanceWindow
Specifies the weekly time range during which maintenance on the cache cluster is
permitted. It is specified as a range in the format ddd:hh24:mi\-ddd:hh24:mi
(24H Clock UTC). The minimum maintenance window is a 60 minute period.
Valid values for ddd are: sun, mon, tue, wed, thu, fri, sat
+.sp
Example: sun:23:00\-mon:01:30
.TP
.B Port
The port number on which each of the cache nodes accepts connections.
+.sp
Default: 6379
.TP
.B NotificationTopicArn
The Amazon Resource Name (ARN) of the Amazon Simple Notification Service (SNS)
topic to which notifications are sent.
-Note: The Amazon SNS topic owner must be the same as the cache cluster owner.
+.sp
+\fBNOTE:\fP
+.INDENT 7.0
+.INDENT 3.5
+The Amazon SNS topic owner must be the same as the cache cluster
+owner.
+.UNINDENT
+.UNINDENT
.TP
.B AutoMinorVersionUpgrade
This (boolean) parameter is currently disabled.
@@ -286042,26 +296759,42 @@ This (boolean) parameter is currently disabled.
.B SnapshotRetentionLimit
The number of days for which ElastiCache retains automatic snapshots before
deleting them.
-Note: This parameter is ONLY valid if the Engine parameter is redis.
+.sp
Default: 0 (i.e., automatic backups are disabled for this cache cluster).
+.sp
+\fBNOTE:\fP
+.INDENT 7.0
+.INDENT 3.5
+This parameter is ONLY valid if the Engine parameter is redis.
+.UNINDENT
+.UNINDENT
.TP
.B SnapshotWindow
The daily time range (in UTC) during which ElastiCache begins taking a daily
snapshot of your node group (shard). If you do not specify this parameter,
ElastiCache automatically chooses an appropriate time range.
-Note: This parameter is ONLY valid if the Engine parameter is redis.
+.sp
Example: 05:00\-09:00
+.sp
+\fBNOTE:\fP
+.INDENT 7.0
+.INDENT 3.5
+This parameter is ONLY valid if the Engine parameter is redis.
+.UNINDENT
+.UNINDENT
.TP
.B AuthToken
The password used to access a password protected server.
+.sp
Password constraints:
.INDENT 7.0
-.INDENT 3.5
+.IP \(bu 2
Must be only printable ASCII characters.
+.IP \(bu 2
Must be at least 16 characters and no more than 128 characters in length.
+.IP \(bu 2
Cannot contain any of the following characters: \(aq/\(aq, \(aq"\(aq, or "@".
.UNINDENT
-.UNINDENT
.TP
.B CacheNodeIdsToRemove
A list of cache node IDs to be removed. A node ID is a numeric identifier (0001, 0002,
@@ -286080,6 +296813,7 @@ Note: This option is only supported on Memcached clusters.
.TP
.B NotificationTopicStatus
The status of the SNS notification topic. Notifications are sent only if the status is active.
+.sp
Valid values: active | inactive
.TP
.B region
@@ -286092,8 +296826,8 @@ Secret key to be used.
Access key to be used.
.TP
.B profile
-A dict with region, key and keyid, or a pillar key (string)
-that contains a dict with region, key and keyid.
+A dict with region, key and keyid, or a pillar key (string) that
+contains a dict with region, key and keyid.
.UNINDENT
.UNINDENT
.INDENT 0.0
@@ -286222,25 +296956,36 @@ dependent resources.
.TP
.B security_groups
One or more VPC security groups (names and/or IDs) associated with the cache cluster.
-Note: This is additive with any sec groups provided via the SecurityGroupIds parameter
+.sp
+\fBNOTE:\fP
.INDENT 7.0
.INDENT 3.5
-below. Use this parameter ONLY when you are creating a cluster in a VPC.
+This is additive with any sec groups provided via the
+SecurityGroupIds parameter below. Use this parameter ONLY when you
+are creating a cluster in a VPC.
.UNINDENT
.UNINDENT
.TP
.B ReplicationGroupId
The replication group identifier. This parameter is stored as a lowercase string.
+.sp
Constraints:
.INDENT 7.0
-.INDENT 3.5
+.IP \(bu 2
A name must contain from 1 to 20 alphanumeric characters or hyphens.
+.IP \(bu 2
The first character must be a letter.
+.IP \(bu 2
A name cannot end with a hyphen or contain two consecutive hyphens.
.UNINDENT
-.UNINDENT
.sp
-Note: In general this parameter is not needed, as \(aqname\(aq is used if it\(aqs not provided.
+\fBNOTE:\fP
+.INDENT 7.0
+.INDENT 3.5
+In general this parameter is not needed, as \(aqname\(aq is used if it\(aqs
+not provided.
+.UNINDENT
+.UNINDENT
.TP
.B ReplicationGroupDescription
A user\-created description for the replication group.
@@ -286254,22 +296999,26 @@ not required if NumCacheClusters, NumNodeGroups, or ReplicasPerNodeGroup is spec
Specifies whether a read\-only replica is automatically promoted to read/write primary if
the existing primary fails. If true, Multi\-AZ is enabled for this replication group. If
false, Multi\-AZ is disabled for this replication group.
-Notes: AutomaticFailoverEnabled must be enabled for Redis (cluster mode enabled)
-.INDENT 7.0
-.INDENT 3.5
-replication groups.
-ElastiCache Multi\-AZ replication groups is not supported on:
-.INDENT 0.0
-.INDENT 3.5
-Redis versions earlier than 2.8.6.
-Redis (cluster mode disabled): T1 and T2 node types. Redis (cluster mode
-enabled): T2 node types.
-.UNINDENT
-.UNINDENT
-.UNINDENT
-.UNINDENT
.sp
Default: False
+.sp
+\fBNOTE:\fP
+.INDENT 7.0
+.INDENT 3.5
+AutomaticFailoverEnabled must be enabled for Redis (cluster mode
+enabled) replication groups.
+.sp
+ElastiCache Multi\-AZ replication groups is not supported on:
+.INDENT 0.0
+.IP \(bu 2
+Redis versions earlier than 2.8.6.
+.IP \(bu 2
+Redis (cluster mode disabled): T1 and T2 node types.
+.IP \(bu 2
+Redis (cluster mode enabled): T2 node types.
+.UNINDENT
+.UNINDENT
+.UNINDENT
.TP
.B NumCacheClusters
The number of clusters this replication group initially has. This parameter is not used
@@ -286284,26 +297033,28 @@ are allocated. The primary cluster is created in the first AZ in the list. This
is not used if there is more than one node group (shard). You should use
NodeGroupConfiguration instead. The number of Availability Zones listed must equal the
value of NumCacheClusters.
-Note: If you are creating your replication group in an Amazon VPC (recommended), you can
-.INDENT 7.0
-.INDENT 3.5
-only locate cache clusters in Availability Zones associated with the subnets in the
-selected subnet group.
-.UNINDENT
-.UNINDENT
.sp
Default: System chosen Availability Zones.
+.sp
+\fBNOTE:\fP
+.INDENT 7.0
+.INDENT 3.5
+If you are creating your replication group in an Amazon VPC
+(recommended), you can only locate cache clusters in Availability
+Zones associated with the subnets in the selected subnet group.
+.UNINDENT
+.UNINDENT
.TP
.B NumNodeGroups
-An optional parameter that specifies the number of node groups (shards) for this Redis
-(cluster mode enabled) replication group. For Redis (cluster mode disabled) either omit
-this parameter or set it to 1.
+An optional parameter that specifies the number of node groups (shards)
+for this Redis (cluster mode enabled) replication group. For Redis
+(cluster mode disabled) either omit this parameter or set it to 1.
+.sp
Default: 1
.TP
.B ReplicasPerNodeGroup
-An optional parameter that specifies the number of replica nodes in each node group
-(shard).
-Valid values are: 0 to 5
+An optional parameter that specifies the number of replica nodes in
+each node group (shard). Valid values are: 0 to 5
.TP
.B NodeGroupConfiguration
A list of node group (shard) configuration options. Each node group (shard) configuration
@@ -286316,14 +297067,6 @@ can omit this parameter. For fiddly details of the expected data layout of this
.B CacheNodeType
The compute and memory capacity of the nodes in the node group (shard).
See \fI\%https://aws.amazon.com/elasticache/pricing/\fP for current sizing, prices, and constraints.
-Notes: All T2 instances are created in an Amazon Virtual Private Cloud (Amazon VPC).
-.INDENT 7.0
-.INDENT 3.5
-Backup/restore is not supported for Redis (cluster mode disabled) T1 and T2 instances.
-Backup/restore is supported on Redis (cluster mode enabled) T2 instances.
-Redis Append\-only files (AOF) functionality is not supported for T1 or T2 instances.
-.UNINDENT
-.UNINDENT
.TP
.B Engine
The name of the cache engine to be used for the cache clusters in this replication group.
@@ -286332,25 +297075,31 @@ The name of the cache engine to be used for the cache clusters in this replicati
The version number of the cache engine to be used for the cache clusters in this replication
group. To view the supported cache engine versions, use the DescribeCacheEngineVersions
operation.
-Note: You can upgrade to a newer engine version but you cannot downgrade to an earlier
+.sp
+\fBNOTE:\fP
.INDENT 7.0
.INDENT 3.5
-engine version. If you want to use an earlier engine version, you must delete the
-existing cache cluster or replication group and create it anew with the earlier
-engine version.
+You can upgrade to a newer engine version but you cannot downgrade
+to an earlier engine version. If you want to use an earlier engine
+version, you must delete the existing cache cluster or replication
+group and create it anew with the earlier engine version.
.UNINDENT
.UNINDENT
.TP
.B CacheParameterGroupName
The name of the parameter group to associate with this replication group. If this argument
is omitted, the default cache parameter group for the specified engine is used.
-Notes: If you are running Redis version 3.2.4 or later, only one node group (shard), and
+.sp
+\fBNOTE:\fP
.INDENT 7.0
.INDENT 3.5
-want to use a default parameter group, we recommend that you specify the parameter
-group by name.
+If you are running Redis version 3.2.4 or later, only one node
+group (shard), and want to use a default parameter group, we
+recommend that you specify the parameter group by name.
+.sp
To create a Redis (cluster mode disabled) replication group, use
CacheParameterGroupName=default.redis3.2
+.sp
To create a Redis (cluster mode enabled) replication group, use
CacheParameterGroupName=default.redis3.2.cluster.on
.UNINDENT
@@ -286358,11 +297107,13 @@ CacheParameterGroupName=default.redis3.2.cluster.on
.TP
.B CacheSubnetGroupName
The name of the cache subnet group to be used for the replication group.
-Note: If you\(aqre going to launch your cluster in an Amazon VPC, you need to create a s
+.sp
+\fBNOTE:\fP
.INDENT 7.0
.INDENT 3.5
-group before you start creating a cluster. For more information, see Subnets and
-Subnet Groups.
+If you\(aqre going to launch your cluster in an Amazon VPC, you need
+to create a s group before you start creating a cluster. For more
+information, see Subnets and Subnet Groups.
.UNINDENT
.UNINDENT
.TP
@@ -286383,7 +297134,13 @@ A list of ARNs that uniquely identify the Redis RDB snapshot files stored in Ama
These snapshot files are used to populate the replication group. The Amazon S3 object name
in the ARN cannot contain any commas. The list must match the number of node groups (shards)
in the replication group, which means you cannot repartition.
-Note: This parameter is only valid if the Engine parameter is redis.
+.sp
+\fBNOTE:\fP
+.INDENT 7.0
+.INDENT 3.5
+This parameter is only valid if the Engine parameter is redis.
+.UNINDENT
+.UNINDENT
.TP
.B SnapshotName
The name of a snapshot from which to restore data into the new replication group. The
@@ -286395,6 +297152,7 @@ Specifies the weekly time range during which maintenance on the cluster is perfo
specified as a range in the format ddd:hh24:mi\-ddd:hh24:mi (24H Clock UTC). The minimum
maintenance window is a 60 minute period.
Valid values for ddd are: sun, mon, tue, wed, thu, fri, sat
+.sp
Example: sun:23:00\-mon:01:30
.TP
.B Port
@@ -286402,7 +297160,13 @@ The port number on which each member of the replication group accepts connection
.TP
.B NotificationTopicArn
The ARN of an SNS topic to which notifications are sent.
-Note: The SNS topic owner must be the same as the cache cluster owner.
+.sp
+\fBNOTE:\fP
+.INDENT 7.0
+.INDENT 3.5
+The SNS topic owner must be the same as the cache cluster owner.
+.UNINDENT
+.UNINDENT
.TP
.B AutoMinorVersionUpgrade
This parameter is currently disabled.
@@ -286410,26 +297174,41 @@ This parameter is currently disabled.
.B SnapshotRetentionLimit
The number of days for which ElastiCache will retain automatic snapshots before deleting
them.
-Note: This parameter is only valid if the Engine parameter is redis .
+.sp
Default: 0 (that is, automatic backups are disabled for this cache cluster).
+.sp
+\fBNOTE:\fP
+.INDENT 7.0
+.INDENT 3.5
+This parameter is only valid if the Engine parameter is redis.
+.UNINDENT
+.UNINDENT
.TP
.B SnapshotWindow
The daily time range (in UTC) during which ElastiCache begins taking a daily snapshot of
your node group (shard). If you do not specify this parameter, ElastiCache automatically
chooses an appropriate time range.
-Note: This parameter is only valid if the Engine parameter is redis .
+.sp
Example: 05:00\-09:00
+.sp
+\fBNOTE:\fP
+.INDENT 7.0
+.INDENT 3.5
+This parameter is only valid if the Engine parameter is redis.
+.UNINDENT
+.UNINDENT
.TP
.B AuthToken
The password used to access a password protected server.
Password constraints:
.INDENT 7.0
-.INDENT 3.5
+.IP \(bu 2
Must be only printable ASCII characters.
+.IP \(bu 2
Must be at least 16 characters and no more than 128 characters in length.
+.IP \(bu 2
Cannot contain any of the following characters: \(aq/\(aq, \(aq"\(aq, or "@".
.UNINDENT
-.UNINDENT
.TP
.B SnapshottingClusterId
The cache cluster ID that is used as the daily snapshot source for the replication group.
@@ -286532,6 +297311,11 @@ mycnamerecord:
.UNINDENT
.INDENT 0.0
.TP
+.B salt.states.boto3_route53.__virtual__()
+Only load if boto is available.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.boto3_route53.hosted_zone_absent(name, Name=None, PrivateZone=False, region=None, key=None, keyid=None, profile=None)
Ensure the Route53 Hostes Zone described is absent
.INDENT 7.0
@@ -286683,9 +297467,8 @@ queries that Amazon Route 53 responds to using the current resource record set.
53 calculates the sum of the weights for the resource record sets that have the same
combination of DNS name and type. Amazon Route 53 then responds to queries based on the
ratio of a resource\(aqs weight to the total.
-.INDENT 7.0
-.TP
-.B Note the following:
+.sp
+Note the following:
.INDENT 7.0
.IP \(bu 2
You must specify a value for the Weight element for every weighted resource record set.
@@ -286704,14 +297487,8 @@ for that resource record set. However, if you set Weight to 0 for all resource
sets that have the same combination of DNS name and type, traffic is routed to all
resources with equal probability. The effect of setting Weight to 0 is different when
you associate health checks with weighted resource record sets. For more information,
-see
-.nf
-\(gaOptions for Configuring Amazon Route 53 Active\-Active and Active\-Passive Failover\(ga__
-.fi
-
+see \fI\%Options for Configuring Amazon Route 53 Active\-Active and Active\-Passive Failover\fP
in the Amazon Route 53 Developer Guide.
-.. __: \fI\%http://docs.aws.amazon.com/Route53/latest/DeveloperGuide/dns\-failover\-configuring\-options.html\fP
-.UNINDENT
.UNINDENT
.TP
.B Region
@@ -286727,30 +297504,25 @@ queries from Africa to be routed to a web server with an IP address of 192.0.2.1
resource record set with a Type of A and a ContinentCode of AF.
.INDENT 7.0
.INDENT 3.5
-.INDENT 0.0
-.TP
-.B ContinentCode
-The two\-letter code for the continent.
-Valid values: AF | AN | AS | EU | OC | NA | SA
-Constraint: Specifying ContinentCode with either CountryCode or SubdivisionCode
-.INDENT 7.0
-.INDENT 3.5
-returns an InvalidInput error.
+.sp
+.nf
+.ft C
+ContinentCode
+ The two\-letter code for the continent.
+ Valid values: AF | AN | AS | EU | OC | NA | SA
+ Constraint: Specifying ContinentCode with either CountryCode or SubdivisionCode
+ returns an InvalidInput error.
+CountryCode
+ The two\-letter code for the country.
+SubdivisionCode
+ The code for the subdivision, for example, a state in the United States or a
+ province in Canada.
+.ft P
+.fi
.UNINDENT
.UNINDENT
-.TP
-.B CountryCode
-The two\-letter code for the country.
-.TP
-.B SubdivisionCode
-The code for the subdivision, for example, a state in the United States or a
-province in Canada.
-.UNINDENT
-.UNINDENT
-.UNINDENT
-.INDENT 7.0
-.TP
-.B Notes
+.sp
+Notes
.INDENT 7.0
.IP \(bu 2
Creating geolocation and geolocation alias resource record sets in private hosted zones
@@ -286765,35 +297537,29 @@ continent to a different resource.
You can\(aqt create two geolocation resource record sets that specify the same geographic
location.
.IP \(bu 2
-The value * in the CountryCode element matches all geographic locations that aren\(aqt
+The value \fB*\fP in the CountryCode element matches all geographic locations that aren\(aqt
specified in other geolocation resource record sets that have the same values for the
Name and Type elements.
.IP \(bu 2
Geolocation works by mapping IP addresses to locations. However, some IP addresses
aren\(aqt mapped to geographic locations, so even if you create geolocation resource
record sets that cover all seven continents, Amazon Route 53 will receive some DNS
-queries from locations that it can\(aqt identify. We recommend that you create a resource
-record set for which the value of CountryCode is
-.nf
-*
-.fi
-, which handles both queries that
-come from locations for which you haven\(aqt created geolocation resource record sets and
-queries from IP addresses that aren\(aqt mapped to a location. If you don\(aqt create a *
-resource record set, Amazon Route 53 returns a "no answer" response for queries from
-those locations.
+queries from locations that it can\(aqt identify. We recommend that you
+create a resource record set for which the value of CountryCode is
+\fB*\fP, which handles both queries that come from locations for which you
+haven\(aqt created geolocation resource record sets and queries from IP
+addresses that aren\(aqt mapped to a location. If you don\(aqt create a \fB*\fP
+resource record set, Amazon Route 53 returns a "no answer" response
+for queries from those locations.
.IP \(bu 2
You can\(aqt create non\-geolocation resource record sets that have the same values for the
Name and Type elements as geolocation resource record sets.
.UNINDENT
-.UNINDENT
.TP
.B TTL
The resource record cache time to live (TTL), in seconds.
Note the following:
.INDENT 7.0
-.INDENT 3.5
-.INDENT 0.0
.IP \(bu 2
If you\(aqre creating an alias resource record set, omit TTL. Amazon Route 53 uses the
value of TTL for the alias target.
@@ -286811,18 +297577,11 @@ that you specify a TTL of 60 seconds for all of the non\-alias weighted resource
sets that have the same name and type. Values other than 60 seconds (the TTL for load
balancers) will change the effect of the values that you specify for Weight.
.UNINDENT
-.UNINDENT
-.UNINDENT
.TP
.B ResourceRecords
A list, containing one or more values for the resource record. No single value can exceed
4,000 characters. For details on how to format values for different record types, see
-
-.nf
-\(gaSupported DNS Resource Record Types\(ga__
-.fi
- in the Amazon Route 53 Developer Guide.
-.. __: \fI\%http://docs.aws.amazon.com/Route53/latest/DeveloperGuide/ResourceRecordTypes.html\fP
+\fI\%Supported DNS Resource Record Types\fP in the Amazon Route 53 Developer Guide.
.sp
Note: You can specify more than one value for all record types except CNAME and SOA.
.sp
@@ -286850,18 +297609,8 @@ instance, so we can then automgically create Route 53 records for them.
The rules governing how to define an AliasTarget for the various supported use\-cases are
obtuse beyond reason and attempting to paraphrase them (or even worse, cut\-and\-paste them
in their entirety) would be silly and counterproductive. If you need this feature, then
-Read The Fine Materials at the
-.nf
-\(gaBoto 3 Route 53 page\(ga__
-.fi
- and/or the
-.nf
-\(gaAWS Route 53 docs\(ga__
-.fi
-
+Read The Fine Materials at the \fI\%Boto 3 Route 53 page\fP and/or the \fI\%AWS Route 53 docs\fP
and suss them for yourself \- I sure won\(aqt claim to understand them partcularly well.
-.. __: \fI\%http://boto3.readthedocs.io/en/latest/reference/services/route53.html#Route53.Client.change_resource_record_sets\fP
-.. __: \fI\%http://docs.aws.amazon.com/Route53/latest/APIReference/API_AliasTarget.html\fP
.TP
.B region
The region to connect to.
@@ -286939,6 +297688,11 @@ Ensure Apigateway API exists:
.UNINDENT
.INDENT 0.0
.TP
+.B salt.states.boto_apigateway.__virtual__()
+Only load if boto is available.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.boto_apigateway.absent(name, api_name, stage_name, nuke_api=False, region=None, key=None, keyid=None, profile=None)
Ensure the stage_name associated with the given api_name deployed by boto_apigateway\(aqs
present state is removed. If the currently associated deployment to the given stage_name has
@@ -286977,8 +297731,6 @@ contains a dict with region, key and keyid.
.INDENT 0.0
.TP
.B salt.states.boto_apigateway.present(name, api_name, swagger_file, stage_name, api_key_required, lambda_integration_role, lambda_region=None, stage_variables=None, region=None, key=None, keyid=None, profile=None, lambda_funcname_format=\(aq{stage}_{api}_{resource}_{method}\(aq, authorization_type=\(aqNONE\(aq, error_response_template=None, response_template=None)
-.INDENT 7.0
-.INDENT 3.5
Ensure the spcified api_name with the corresponding swaggerfile is deployed to the
given stage_name in AWS ApiGateway.
.sp
@@ -286987,50 +297739,59 @@ handled through a Mock integration.
.sp
There may be multiple deployments for the API object, each deployment is tagged with a description
(i.e. unique label) in pretty printed json format consisting of the following key/values.
-.INDENT 0.0
+.INDENT 7.0
.INDENT 3.5
-.INDENT 0.0
-.TP
-.B {
-"api_name": api_name,
-"swagger_file": basename_of_swagger_file
-"swagger_file_md5sum": md5sum_of_swagger_file,
-"swagger_info_object": info_object_content_in_swagger_file
-.UNINDENT
.sp
+.nf
+.ft C
+{
+ "api_name": api_name,
+ "swagger_file": basename_of_swagger_file
+ "swagger_file_md5sum": md5sum_of_swagger_file,
+ "swagger_info_object": info_object_content_in_swagger_file
}
+.ft P
+.fi
.UNINDENT
.UNINDENT
.sp
Please note that the name of the lambda function to be integrated will be derived
via the provided lambda_funcname_format parameters:
-.INDENT 0.0
-.INDENT 3.5
-the default lambda_funcname_format is a string with the following substitutable keys:
-"{stage}_{api}_{resource}_{method}". The user can choose to reorder the known keys.
-.sp
+.INDENT 7.0
+.IP \(bu 2
+the default lambda_funcname_format is a string with the following
+substitutable keys: "{stage}_{api}_{resource}_{method}". The user can
+choose to reorder the known keys.
+.IP \(bu 2
the stage key corresponds to the stage_name passed in.
+.IP \(bu 2
the api key corresponds to the api_name passed in.
+.IP \(bu 2
the resource corresponds to the resource path defined in the passed swagger file.
+.IP \(bu 2
the method corresponds to the method for a resource path defined in the passed swagger file.
+.UNINDENT
.sp
-for the default lambda_funcname_format, given the following
-input:
-.INDENT 0.0
+For the default lambda_funcname_format, given the following input:
+.INDENT 7.0
.INDENT 3.5
+.sp
+.nf
+.ft C
api_name = \(aq Test Service\(aq
stage_name = \(aqalpha\(aq
basePath = \(aq/api\(aq
path = \(aq/a/{b}/c\(aq
method = \(aqPOST\(aq
+.ft P
+.fi
.UNINDENT
.UNINDENT
-.INDENT 0.0
-.TP
-.B we will end up with the following Lambda Function Name that will be looked up:
-\(aqtest_service_alpha_a_b_c_post\(aq
-.TP
-.B The canconicalization of these input parameters is done in the following order:
+.sp
+We will end up with the following Lambda Function Name that will be looked
+up: \(aqtest_service_alpha_a_b_c_post\(aq
+.sp
+The canconicalization of these input parameters is done in the following order:
.INDENT 7.0
.IP 1. 3
lambda_funcname_format is formatted with the input parameters as passed,
@@ -287043,19 +297804,39 @@ consecutive spaces and forward slashes in the paths are replaced with \(aq_\(aq
.IP 5. 3
consecutive \(aq_\(aq are replaced with \(aq_\(aq
.UNINDENT
-.UNINDENT
-.UNINDENT
-.UNINDENT
.sp
Please note that for error response handling, the swagger file must have an error response model
with the following schema. The lambda functions should throw exceptions for any non successful responses.
An optional pattern field can be specified in errorMessage field to aid the response mapping from Lambda
to the proper error return status codes.
-.INDENT 0.0
+.INDENT 7.0
.INDENT 3.5
+.sp
+.nf
+.ft C
+Error:
+ type: object
+ properties:
+ stackTrace:
+ type: array
+ items:
+ type: array
+ items:
+ type: string
+ description: call stack
+ errorType:
+ type: string
+ description: error type
+ errorMessage:
+ type: string
+ description: |
+ Error message, will be matched based on pattern.
+ If no pattern is specified, the default pattern used for response mapping will be +*.
+.ft P
+.fi
.UNINDENT
.UNINDENT
-.INDENT 0.0
+.INDENT 7.0
.TP
.B name
The name of the state definition
@@ -287085,13 +297866,14 @@ priority:
.INDENT 7.0
.IP 1. 3
lambda_region as passed in (is not None)
+.IP 2. 3
+if lambda_region is None, use the region as if a boto_lambda
+function were executed without explicitly specifying lambda region.
+.IP 3. 3
+if region determined in (2) is different than the region used by
+boto_apigateway functions, a final lookup will be attempted using
+the boto_apigateway region.
.UNINDENT
-.sp
-2) if lambda_region is None, use the region as if a boto_lambda function were
-executed without explicitly specifying lambda region.
-3) if region determined in (2) is different than the region used by
-boto_apigateway functions, a final lookup will be attempted using the
-boto_apigateway region.
.TP
.B stage_variables
A dict with variables and their values, or a pillar key (string) that
@@ -287122,110 +297904,45 @@ swagger spec file. Default is set to \(aqNONE\(aq
.TP
.B error_response_template
String value that defines the response template mapping that should be applied in cases error occurs.
-Refer to AWS documentation for details:
+Refer to AWS documentation for details: \fI\%http://docs.aws.amazon.com/apigateway/latest/developerguide/api\-gateway\-mapping\-template\-reference.html\fP
+.sp
+If set to None, the following default value is used:
.INDENT 7.0
.INDENT 3.5
-\fI\%http://docs.aws.amazon.com/apigateway/latest/developerguide/api\-gateway\-mapping\-template\-reference.html\fP
+.sp
+.nf
+.ft C
+\(aq#set($inputRoot = $input.path(\(aq$\(aq))\en\(aq
+\(aq{\en\(aq
+\(aq "errorMessage" : "$inputRoot.errorMessage",\en\(aq
+\(aq "errorType" : "$inputRoot.errorType",\en\(aq
+\(aq "stackTrace" : [\en\(aq
+\(aq#foreach($stackTrace in $inputRoot.stackTrace)\en\(aq
+\(aq [\en\(aq
+\(aq#foreach($elem in $stackTrace)\en\(aq
+\(aq "$elem"\en\(aq
+\(aq#if($foreach.hasNext),#end\en\(aq
+\(aq#end\en\(aq
+\(aq ]\en\(aq
+\(aq#if($foreach.hasNext),#end\en\(aq
+\(aq#end\en\(aq
+\(aq ]\en\(aq
+.ft P
+.fi
.UNINDENT
.UNINDENT
-.INDENT 7.0
-.TP
-.B If set to None, the following default value is used:
-\(aq#set($inputRoot = $input.path(\(aq$\(aq))
-.UNINDENT
-.UNINDENT
-.UNINDENT
-.UNINDENT
-.INDENT 7.0
-.TP
-.B \(aq
-\(aq{
-.UNINDENT
-.INDENT 7.0
-.TP
-.B \(aq
-\(aq "errorMessage" : "$inputRoot.errorMessage",
-.UNINDENT
-.INDENT 7.0
-.TP
-.B \(aq
-\(aq "errorType" : "$inputRoot.errorType",
-.UNINDENT
-.INDENT 7.0
-.TP
-.B \(aq
-\(aq "stackTrace" : [
-.UNINDENT
-.INDENT 7.0
-.TP
-.B \(aq
-\(aq#foreach($stackTrace in $inputRoot.stackTrace)
-.UNINDENT
-.INDENT 7.0
-.TP
-.B \(aq
-\(aq [
-.UNINDENT
-.INDENT 7.0
-.TP
-.B \(aq
-\(aq#foreach($elem in $stackTrace)
-.UNINDENT
-.INDENT 7.0
-.TP
-.B \(aq
-\(aq "$elem"
-.UNINDENT
-.INDENT 7.0
-.TP
-.B \(aq
-\(aq#if($foreach.hasNext),#end
-.UNINDENT
-.INDENT 7.0
-.TP
-.B \(aq
-\(aq#end
-.UNINDENT
-.INDENT 7.0
-.TP
-.B \(aq
-\(aq ]
-.UNINDENT
-.INDENT 7.0
-.TP
-.B \(aq
-\(aq#if($foreach.hasNext),#end
-.UNINDENT
-.INDENT 7.0
-.TP
-.B \(aq
-\(aq#end
-.UNINDENT
-.INDENT 7.0
-.TP
-.B \(aq
-\(aq ]
-.UNINDENT
.sp
-\(aq
-.INDENT 7.0
-.INDENT 3.5
-.INDENT 0.0
-.INDENT 3.5
New in version 2017.7.0.
-.UNINDENT
-.UNINDENT
-.INDENT 0.0
.TP
.B response_template
-String value that defines the response template mapping applied in case of success (including OPTIONS method)
-If set to None, empty ({}) template is assumed, which will transfer response from the lambda function as is.
+String value that defines the response template mapping applied in case
+of success (including OPTIONS method) If set to None, empty ({})
+template is assumed, which will transfer response from the lambda
+function as is.
.sp
New in version 2017.7.0.
-.UNINDENT
-.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
@@ -287647,6 +298364,11 @@ Ensure myasg exists:
.UNINDENT
.INDENT 0.0
.TP
+.B salt.states.boto_asg.__virtual__()
+Only load if boto is available.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.boto_asg.absent(name, force=False, region=None, key=None, keyid=None, profile=None, remove_lc=False)
Ensure the named autoscale group is deleted.
.INDENT 7.0
@@ -287959,6 +298681,11 @@ stack\-absent:
.UNINDENT
.INDENT 0.0
.TP
+.B salt.states.boto_cfn.__virtual__()
+Only load if elementtree xml library and boto are available.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.boto_cfn.absent(name, region=None, key=None, keyid=None, profile=None)
Ensure cloud formation stack is absent.
.sp
@@ -288109,6 +298836,11 @@ Ensure trail exists:
.UNINDENT
.INDENT 0.0
.TP
+.B salt.states.boto_cloudtrail.__virtual__()
+Only load if boto is available.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.boto_cloudtrail.absent(name, Name, region=None, key=None, keyid=None, profile=None)
Ensure trail with passed properties is absent.
.INDENT 7.0
@@ -288276,6 +299008,11 @@ my test alarm:
.UNINDENT
.INDENT 0.0
.TP
+.B salt.states.boto_cloudwatch_alarm.__virtual__()
+Only load if boto is available.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.boto_cloudwatch_alarm.absent(name, region=None, key=None, keyid=None, profile=None)
Ensure the named cloudwatch alarm is deleted.
.INDENT 7.0
@@ -288392,6 +299129,11 @@ Ensure event rule exists:
.UNINDENT
.INDENT 0.0
.TP
+.B salt.states.boto_cloudwatch_event.__virtual__()
+Only load if boto is available.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.boto_cloudwatch_event.absent(name, Name=None, region=None, key=None, keyid=None, profile=None)
Ensure CloudWatch event rule with passed properties is absent.
.INDENT 7.0
@@ -288431,11 +299173,7 @@ Name of the event rule. Defaults to the value of the \(aqname\(aq param if
not provided.
.TP
.B ScheduleExpression
-The scheduling expression. For example, "cron(0 20 * * ?
-.nf
-*
-.fi
-)",
+The scheduling expression. For example, \fBcron(0 20 * * ? *)\fP,
"rate(5 minutes)"
.TP
.B EventPattern
@@ -288531,6 +299269,11 @@ Ensure function exists:
.UNINDENT
.INDENT 0.0
.TP
+.B salt.states.boto_cognitoidentity.__virtual__()
+Only load if boto is available.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.boto_cognitoidentity.pool_absent(name, IdentityPoolName, RemoveAllMatched=False, region=None, key=None, keyid=None, profile=None)
Ensure cognito identity pool with passed properties is absent.
.INDENT 7.0
@@ -288684,6 +299427,11 @@ Ensure daily data pipeline exists:
.UNINDENT
.INDENT 0.0
.TP
+.B salt.states.boto_datapipeline.__virtual__()
+Only load if boto is available.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.boto_datapipeline.absent(name, region=None, key=None, keyid=None, profile=None)
Ensure a pipeline with the service_name does not exist
.INDENT 7.0
@@ -288936,6 +299684,11 @@ Raised when a global secondary index cannot be updated.
.UNINDENT
.INDENT 0.0
.TP
+.B salt.states.boto_dynamodb.__virtual__()
+Only load if boto_dynamodb is available.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.boto_dynamodb.absent(name, region=None, key=None, keyid=None, profile=None)
Ensure the DynamoDB table does not exist.
.INDENT 7.0
@@ -288964,13 +299717,10 @@ Ensure the DynamoDB table exists. Table throughput can be updated after
table creation.
.sp
Global secondary indexes (GSIs) are managed with some exceptions:
-* If a GSI deletion is detected, a failure will occur (deletes should be
.INDENT 7.0
-.INDENT 3.5
+.IP \(bu 2
+If a GSI deletion is detected, a failure will occur (deletes should be
done manually in the AWS console).
-.UNINDENT
-.UNINDENT
-.INDENT 7.0
.IP \(bu 2
If multiple GSIs are added in a single Salt call, a failure will occur
(boto supports one creation at a time). Note that this only applies after
@@ -289108,6 +299858,11 @@ delete\-key\-pair:
.UNINDENT
.INDENT 0.0
.TP
+.B salt.states.boto_ec2.__virtual__()
+Only load if boto is available.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.boto_ec2.eni_absent(name, release_eip=False, region=None, key=None, keyid=None, profile=None)
Ensure the EC2 ENI is absent.
.sp
@@ -289204,6 +299959,9 @@ that contains a dict with region, key and keyid.
.TP
.B salt.states.boto_ec2.instance_absent(name, instance_name=None, instance_id=None, release_eip=False, region=None, key=None, keyid=None, profile=None, filters=None)
Ensure an EC2 instance does not exist (is stopped and removed).
+.sp
+Changed in version 2016.11.0.
+
.INDENT 7.0
.TP
.B name
@@ -289237,6 +299995,17 @@ delete.
.UNINDENT
.sp
YAML example fragment:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+\- filters:
+ vpc\-id: vpc\-abcdef12
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
@@ -289323,15 +300092,11 @@ be terminated via the API.
(string) – Specifies whether the instance stops or terminates on
instance\-initiated shutdown. Valid values are:
.INDENT 7.0
-.INDENT 3.5
-.INDENT 0.0
.IP \(bu 2
\(aqstop\(aq
.IP \(bu 2
\(aqterminate\(aq
.UNINDENT
-.UNINDENT
-.UNINDENT
.TP
.B placement_group
(string) – If specified, this is the name of the placement group in
@@ -289402,8 +300167,6 @@ New in version 2016.11.0.
(dict) \- Instance attributes and value to be applied to the instance.
Available options are:
.INDENT 7.0
-.INDENT 3.5
-.INDENT 0.0
.IP \(bu 2
instanceType \- A valid instance type (m1.small)
.IP \(bu 2
@@ -289427,22 +300190,16 @@ ebsOptimized \- Boolean (false)
.IP \(bu 2
sriovNetSupport \- String \- ie: ‘simple’
.UNINDENT
-.UNINDENT
-.UNINDENT
.TP
.B target_state
(string) \- The desired target state of the instance. Available options
are:
.INDENT 7.0
-.INDENT 3.5
-.INDENT 0.0
.IP \(bu 2
running
.IP \(bu 2
stopped
.UNINDENT
-.UNINDENT
-.UNINDENT
.sp
Note that this option is currently UNIMPLEMENTED.
.TP
@@ -289565,6 +300322,33 @@ volumes can be all tagged differently with one call to this function.
.sp
YAML example fragment:
.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+\- filters:
+ attachment.instance_id: i\-abcdef12
+ tags:
+ Name: dev\-int\-abcdef12.aws\-foo.com
+\- filters:
+ attachment.device: /dev/sdf
+ tags:
+ ManagedSnapshots: true
+ BillingGroup: bubba.hotep@aws\-foo.com
+\- filters:
+ instance_name: prd\-foo\-01.aws\-foo.com
+ tags:
+ Name: prd\-foo\-01.aws\-foo.com
+ BillingGroup: infra\-team@aws\-foo.com
+\- filters:
+ volume_ids: [ vol\-12345689, vol\-abcdef12 ]
+ tags:
+ BillingGroup: infra\-team@aws\-foo.com
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.INDENT 7.0
.TP
.B authoritative
Should un\-declared tags currently set on matched volumes be deleted? Boolean.
@@ -289677,6 +300461,11 @@ Ensure myelasticache exists:
.UNINDENT
.INDENT 0.0
.TP
+.B salt.states.boto_elasticache.__virtual__()
+Only load if boto is available.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.boto_elasticache.absent(name, wait=True, region=None, key=None, keyid=None, profile=None)
Ensure the named elasticache cluster is deleted.
.INDENT 7.0
@@ -289900,9 +300689,9 @@ config:
.nf
.ft C
myprofile:
- keyid: GKTADJGHEIQSXMKKRBJ08H
- key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs
- region: us\-east\-1
+ keyid: GKTADJGHEIQSXMKKRBJ08H
+ key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs
+ region: us\-east\-1
.ft P
.fi
.UNINDENT
@@ -289935,12 +300724,12 @@ Ensure domain exists:
AWS: "*"
\- Action:
\- "es:*"
- \- Resource: "arn:aws:es:*:111111111111:domain/mydomain/*
+ \- Resource: "arn:aws:es:*:111111111111:domain/mydomain/*"
\- Condition:
IpAddress:
"aws:SourceIp":
- \- "127.0.0.1",
- \- "127.0.0.2",
+ \- "127.0.0.1"
+ \- "127.0.0.2"
\- SnapshotOptions:
AutomatedSnapshotStartHour: 0
\- AdvancedOptions:
@@ -289956,6 +300745,11 @@ Ensure domain exists:
.UNINDENT
.INDENT 0.0
.TP
+.B salt.states.boto_elasticsearch_domain.__virtual__()
+Only load if boto is available.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.boto_elasticsearch_domain.absent(name, DomainName, region=None, key=None, keyid=None, profile=None)
Ensure domain with passed properties is absent.
.INDENT 7.0
@@ -290360,6 +301154,11 @@ Ensure myelb ELB exists:
.UNINDENT
.INDENT 0.0
.TP
+.B salt.states.boto_elb.__virtual__()
+Only load if boto is available.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.boto_elb.absent(name, region=None, key=None, keyid=None, profile=None)
Ensure an ELB does not exist
.INDENT 7.0
@@ -290583,6 +301382,11 @@ myprofile:
.UNINDENT
.INDENT 0.0
.TP
+.B salt.states.boto_elbv2.__virtual__()
+Only load if boto is available.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.boto_elbv2.targets_deregistered(name, targets, region=None, key=None, keyid=None, profile=None)
Remove targets to an Application Load Balancer target group.
.INDENT 7.0
@@ -290834,6 +301638,11 @@ add\-saml\-provider:
.UNINDENT
.INDENT 0.0
.TP
+.B salt.states.boto_iam.__virtual__()
+Only load if elementtree xml library and boto are available.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.boto_iam.account_policy(name=None, allow_users_to_change_password=None, hard_expiry=None, max_password_age=None, minimum_password_length=None, password_reuse_prevention=None, require_lowercase_characters=None, require_numbers=None, require_symbols=None, require_uppercase_characters=None, region=None, key=None, keyid=None, profile=None)
Change account policy.
.sp
@@ -291002,13 +301811,11 @@ that contains a dict with region, key and keyid.
.INDENT 0.0
.TP
.B salt.states.boto_iam.keys_present(name, number, save_dir, region=None, key=None, keyid=None, profile=None, save_format=\(aq{2}\en{0}\en{3}\en{1}\en\(aq)
-.INDENT 7.0
-.INDENT 3.5
New in version 2015.8.0.
.sp
Ensure the IAM access keys are present.
-.INDENT 0.0
+.INDENT 7.0
.TP
.B name (string)
The name of the new user.
@@ -291034,20 +301841,10 @@ A dict with region, key and keyid, or a pillar key (string)
that contains a dict with region, key and keyid.
.TP
.B save_format (dict)
-Save format is repeated for each key. Default format is "{2}
-.UNINDENT
-.UNINDENT
-.UNINDENT
-.sp
-{0}
-{3}
-{1}
-",
-.INDENT 7.0
-.INDENT 3.5
-where {0} and {1} are placeholders for new key_id and key respectively,
-whereas {2} and {3} are "key_id\-{number}" and \(aqkey\-{number}\(aq strings kept for compatibility.
-.UNINDENT
+Save format is repeated for each key. Default format is
+"{2}n{0}n{3}n{1}n", where {0} and {1} are placeholders for new
+key_id and key respectively, whereas {2} and {3} are "key_id\-{number}"
+and \(aqkey\-{number}\(aq strings kept for compatibility.
.UNINDENT
.UNINDENT
.INDENT 0.0
@@ -291114,6 +301911,9 @@ that contains a dict with region, key and keyid.
.INDENT 0.0
.TP
.B salt.states.boto_iam.saml_provider_absent(name, region=None, key=None, keyid=None, profile=None)
+New in version 2016.11.0.
+
+.sp
Ensure the SAML provider with the specified name is absent.
.INDENT 7.0
.TP
@@ -291140,6 +301940,9 @@ that contains a dict with region, key and keyid.
.INDENT 0.0
.TP
.B salt.states.boto_iam.saml_provider_present(name, saml_metadata_document, region=None, key=None, keyid=None, profile=None)
+New in version 2016.11.0.
+
+.sp
Ensure the SAML provider with the specified name is present.
.INDENT 7.0
.TP
@@ -291425,6 +302228,11 @@ will be used as the default region.
.UNINDENT
.INDENT 0.0
.TP
+.B salt.states.boto_iam_role.__virtual__()
+Only load if boto is available.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.boto_iam_role.absent(name, region=None, key=None, keyid=None, profile=None)
Ensure the IAM role is deleted.
.INDENT 7.0
@@ -291604,6 +302412,11 @@ Ensure topic rule exists:
.UNINDENT
.INDENT 0.0
.TP
+.B salt.states.boto_iot.__virtual__()
+Only load if boto is available.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.boto_iot.policy_absent(name, policyName, region=None, key=None, keyid=None, profile=None)
Ensure policy with passed properties is absent.
.INDENT 7.0
@@ -291920,6 +302733,11 @@ Ensure Kinesis stream exists:
.UNINDENT
.INDENT 0.0
.TP
+.B salt.states.boto_kinesis.__virtual__()
+Only load if boto_kinesis is available.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.boto_kinesis.absent(name, region=None, key=None, keyid=None, profile=None)
Delete the kinesis stream, if it exists.
.INDENT 7.0
@@ -292062,6 +302880,11 @@ Ensure mykey key exists:
.UNINDENT
.INDENT 0.0
.TP
+.B salt.states.boto_kms.__virtual__()
+Only load if boto is available.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.boto_kms.key_present(name, policy, description=None, key_usage=None, grants=None, manage_grants=False, key_rotation=False, enabled=True, region=None, key=None, keyid=None, profile=None)
Ensure the KMS key exists. KMS keys can not be deleted, so this function
must be used to ensure the key is enabled or disabled.
@@ -292190,6 +303013,11 @@ Ensure function exists:
.UNINDENT
.INDENT 0.0
.TP
+.B salt.states.boto_lambda.__virtual__()
+Only load if boto is available.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.boto_lambda.alias_absent(name, FunctionName, Name, region=None, key=None, keyid=None, profile=None)
Ensure alias with passed properties is absent.
.INDENT 7.0
@@ -292424,6 +303252,26 @@ to an image processing function. The default value is 128 MB. The value must be
If your Lambda function accesses resources in a VPC, you must provide this parameter
identifying the list of security group IDs/Names and subnet IDs/Name. These must all belong
to the same VPC. This is a dict of the form:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+VpcConfig:
+ SecurityGroupNames:
+ \- mysecgroup1
+ \- mysecgroup2
+ SecurityGroupIds:
+ \- sg\-abcdef1234
+ SubnetNames:
+ \- mysubnet1
+ SubnetIds:
+ \- subnet\-1234abcd
+ \- subnet\-abcd1234
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
.sp
If VpcConfig is provided at all, you MUST pass at least one security group and one subnet.
.TP
@@ -292438,21 +303286,21 @@ atuomatically retry this number of times. The default is 5.
.B Environment
The parent object that contains your environment\(aqs configuration
settings. This is a dictionary of the form:
-{
.INDENT 7.0
.INDENT 3.5
-.INDENT 0.0
-.TP
-.B \(aqVariables\(aq: {
-\(aqVariableName\(aq: \(aqVariableValue\(aq
-.UNINDENT
.sp
+.nf
+.ft C
+{
+ \(aqVariables\(aq: {
+ \(aqVariableName\(aq: \(aqVariableValue\(aq
+ }
}
+.ft P
+.fi
.UNINDENT
.UNINDENT
.sp
-}
-.sp
New in version 2017.7.0.
.TP
@@ -292589,6 +303437,11 @@ Ensure mylc exists:
.UNINDENT
.INDENT 0.0
.TP
+.B salt.states.boto_lc.__virtual__()
+Only load if boto is available.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.boto_lc.absent(name, region=None, key=None, keyid=None, profile=None)
Ensure the named launch configuration is deleted.
.INDENT 7.0
@@ -292819,6 +303672,11 @@ boto3
.UNINDENT
.INDENT 0.0
.TP
+.B salt.states.boto_rds.__virtual__()
+Only load if boto is available.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.boto_rds.absent(name, skip_final_snapshot=None, final_db_snapshot_identifier=None, tags=None, region=None, key=None, keyid=None, profile=None, wait_for_deletion=True, timeout=180)
Ensure RDS instance is absent.
.INDENT 7.0
@@ -293221,6 +304079,11 @@ myarecord:
.UNINDENT
.INDENT 0.0
.TP
+.B salt.states.boto_route53.__virtual__()
+Only load if boto is available.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.boto_route53.absent(name, zone, record_type, identifier=None, region=None, key=None, keyid=None, profile=None, wait_for_sync=True, split_dns=False, private_zone=False)
Ensure the Route53 record is deleted.
.INDENT 7.0
@@ -293282,16 +304145,11 @@ Ensure a hosted zone exists with the given attributes. Note that most
things cannot be modified once a zone is created \- it must be deleted and
re\-spun to update these attributes:
.INDENT 7.0
-.INDENT 3.5
-.INDENT 0.0
.IP \(bu 2
private_zone (AWS API limitation).
.IP \(bu 2
-.INDENT 2.0
-.TP
-.B comment (the appropriate call exists in the AWS API and in boto3, but
-has not, as of this writing, been added to boto2).
-.UNINDENT
+comment (the appropriate call exists in the AWS API and in boto3, but has
+not, as of this writing, been added to boto2).
.IP \(bu 2
vpc_id (same story \- we really need to rewrite this module with boto3)
.IP \(bu 2
@@ -293299,8 +304157,6 @@ vpc_name (really just a pointer to vpc_id anyway).
.IP \(bu 2
vpc_region (again, supported in boto3 but not boto2).
.UNINDENT
-.UNINDENT
-.UNINDENT
.INDENT 7.0
.TP
.B name
@@ -293442,7 +304298,7 @@ config:
myprofile:
keyid: GKTADJGHEIQSXMKKRBJ08H
key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs
- region: us\-east\-1
+ region: us\-east\-1
.ft P
.fi
.UNINDENT
@@ -293552,6 +304408,11 @@ Ensure bucket exists:
.UNINDENT
.INDENT 0.0
.TP
+.B salt.states.boto_s3_bucket.__virtual__()
+Only load if boto is available.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.boto_s3_bucket.absent(name, Bucket, Force=False, region=None, key=None, keyid=None, profile=None)
Ensure bucket with passed properties is absent.
.INDENT 7.0
@@ -293765,6 +304626,11 @@ will be used as the default region.
.UNINDENT
.INDENT 0.0
.TP
+.B salt.states.boto_secgroup.__virtual__()
+Only load if boto is available.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.boto_secgroup.absent(name, vpc_id=None, vpc_name=None, region=None, key=None, keyid=None, profile=None)
Ensure a security group with the specified name does not exist.
.INDENT 7.0
@@ -293925,6 +304791,11 @@ mytopic:
.UNINDENT
.INDENT 0.0
.TP
+.B salt.states.boto_sns.__virtual__()
+Only load if boto is available.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.boto_sns.absent(name, region=None, key=None, keyid=None, profile=None, unsubscribe=False)
Ensure the named sns topic is deleted.
.INDENT 7.0
@@ -294072,6 +304943,11 @@ myqueue:
.UNINDENT
.INDENT 0.0
.TP
+.B salt.states.boto_sqs.__virtual__()
+Only load if boto is available.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.boto_sqs.absent(name, region=None, key=None, keyid=None, profile=None)
Ensure the named sqs queue is deleted.
.INDENT 7.0
@@ -294166,9 +305042,9 @@ config:
.nf
.ft C
myprofile:
- keyid: GKTADJGHEIQSXMKKRBJ08H
- key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs
- region: us\-east\-1
+ keyid: GKTADJGHEIQSXMKKRBJ08H
+ key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs
+ region: us\-east\-1
.ft P
.fi
.UNINDENT
@@ -294179,12 +305055,12 @@ myprofile:
.nf
.ft C
aws:
- region:
- us\-east\-1:
- profile:
- keyid: GKTADJGHEIQSXMKKRBJ08H
- key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs
- region: us\-east\-1
+ region:
+ us\-east\-1:
+ profile:
+ keyid: GKTADJGHEIQSXMKKRBJ08H
+ key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs
+ region: us\-east\-1
.ft P
.fi
.UNINDENT
@@ -294195,43 +305071,43 @@ aws:
.nf
.ft C
Ensure VPC exists:
- boto_vpc.present:
- \- name: myvpc
- \- cidr_block: 10.10.11.0/24
- \- dns_hostnames: True
- \- region: us\-east\-1
- \- keyid: GKTADJGHEIQSXMKKRBJ08H
- \- key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs
+ boto_vpc.present:
+ \- name: myvpc
+ \- cidr_block: 10.10.11.0/24
+ \- dns_hostnames: True
+ \- region: us\-east\-1
+ \- keyid: GKTADJGHEIQSXMKKRBJ08H
+ \- key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs
Ensure subnet exists:
- boto_vpc.subnet_present:
- \- name: mysubnet
- \- vpc_id: vpc\-123456
- \- cidr_block: 10.0.0.0/16
- \- region: us\-east\-1
- \- profile: myprofile
+ boto_vpc.subnet_present:
+ \- name: mysubnet
+ \- vpc_id: vpc\-123456
+ \- cidr_block: 10.0.0.0/16
+ \- region: us\-east\-1
+ \- profile: myprofile
{% set profile = salt[\(aqpillar.get\(aq](\(aqaws:region:us\-east\-1:profile\(aq ) %}
Ensure internet gateway exists:
- boto_vpc.internet_gateway_present:
- \- name: myigw
- \- vpc_name: myvpc
- \- profile: {{ profile }}
+ boto_vpc.internet_gateway_present:
+ \- name: myigw
+ \- vpc_name: myvpc
+ \- profile: {{ profile }}
Ensure route table exists:
- boto_vpc.route_table_present:
- \- name: my_route_table
- \- vpc_id: vpc\-123456
- \- routes:
- \- destination_cidr_block: 0.0.0.0/0
- instance_id: i\-123456
- \- subnet_names:
- \- subnet1
- \- subnet2
- \- region: us\-east\-1
- \- profile:
- keyid: GKTADJGHEIQSXMKKRBJ08H
- key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs
+ boto_vpc.route_table_present:
+ \- name: my_route_table
+ \- vpc_id: vpc\-123456
+ \- routes:
+ \- destination_cidr_block: 0.0.0.0/0
+ instance_id: i\-123456
+ \- subnet_names:
+ \- subnet1
+ \- subnet2
+ \- region: us\-east\-1
+ \- profile:
+ keyid: GKTADJGHEIQSXMKKRBJ08H
+ key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs
.ft P
.fi
.UNINDENT
@@ -294314,6 +305190,11 @@ delete a vpc peering connection by id:
.UNINDENT
.INDENT 0.0
.TP
+.B salt.states.boto_vpc.__virtual__()
+Only load if boto is available.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.boto_vpc.absent(name, tags=None, region=None, key=None, keyid=None, profile=None)
Ensure VPC with passed properties is absent.
.INDENT 7.0
@@ -294377,12 +305258,12 @@ Example:
.nf
.ft C
boto_vpc.accept_vpc_peering_connection:
- \- conn_name: salt_peering_connection
+ \- conn_name: salt_peering_connection
# usage with vpc peering connection id and region
boto_vpc.accept_vpc_peering_connection:
- \- conn_id: pbx\-1873d472
- \- region: us\-west\-2
+ \- conn_id: pbx\-1873d472
+ \- region: us\-west\-2
.ft P
.fi
.UNINDENT
@@ -294673,7 +305554,7 @@ Example:
.nf
.ft C
boto_vpc.nat_gateway_present:
- \- subnet_name: my\-subnet
+ \- subnet_name: my\-subnet
.ft P
.fi
.UNINDENT
@@ -294844,17 +305725,17 @@ Example:
.nf
.ft C
boto_vpc.route_table_present:
- \- name: my_route_table
- \- vpc_id: vpc\-123456
- \- routes:
- \- destination_cidr_block: 0.0.0.0/0
- internet_gateway_name: InternetGateway
- \- destination_cidr_block: 10.10.11.0/24
- instance_id: i\-123456
- \- destination_cidr_block: 10.10.12.0/24
- interface_id: eni\-123456
- \- destination_cidr_block: 10.10.13.0/24
- instance_name: mygatewayserver
+ \- name: my_route_table
+ \- vpc_id: vpc\-123456
+ \- routes:
+ \- destination_cidr_block: 0.0.0.0/0
+ internet_gateway_name: InternetGateway
+ \- destination_cidr_block: 10.10.11.0/24
+ instance_id: i\-123456
+ \- destination_cidr_block: 10.10.12.0/24
+ interface_id: eni\-123456
+ \- destination_cidr_block: 10.10.13.0/24
+ instance_name: mygatewayserver
\- subnet_names:
\- subnet1
\- subnet2
@@ -295078,6 +305959,11 @@ underscore:
.UNINDENT
.INDENT 0.0
.TP
+.B salt.states.bower.__virtual__()
+Only load if the bower module is available in __salt__
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.bower.bootstrap(name, user=None)
Bootstraps a frontend distribution.
.sp
@@ -295202,6 +306088,11 @@ require:
.UNINDENT
.INDENT 0.0
.TP
+.B salt.states.cabal.__virtual__()
+Only work when cabal\-install is installed.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.cabal.installed(name, pkgs=None, user=None, install_global=False, env=None)
Verify that the given package is installed and is at the correct version
(if specified).
@@ -295295,6 +306186,11 @@ my\-solo\-run:
.UNINDENT
.INDENT 0.0
.TP
+.B salt.states.chef.__virtual__()
+Only load if Chef execution module is available.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.chef.client(name, **kwargs)
.INDENT 7.0
.TP
@@ -295405,6 +306301,11 @@ Manage Chocolatey package installs
.. versionadded:: 2016.3.0
.INDENT 0.0
.TP
+.B salt.states.chocolatey.__virtual__()
+Load only if chocolatey is loaded
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.chocolatey.installed(name, version=None, source=None, force=False, pre_versions=False, install_args=None, override_args=False, force_x86=False, package_args=None, allow_multiple=False)
Installs a package if not already installed
.INDENT 7.0
@@ -295609,6 +306510,11 @@ my\-ec2\-instance:
.UNINDENT
.INDENT 0.0
.TP
+.B salt.states.cloud.__virtual__()
+Only load if the cloud module is available in __salt__
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.cloud.absent(name, onlyif=None, unless=None)
Ensure that no instances with the specified names exist.
.sp
@@ -295723,7 +306629,7 @@ A simple example to execute a command:
.nf
.ft C
# Store the current date in a file
-date > /tmp/salt\-run:
+\(aqdate > /tmp/salt\-run\(aq:
cmd.run
.ft P
.fi
@@ -295737,7 +306643,7 @@ no disk space:
.sp
.nf
.ft C
-> /var/log/messages:
+\(aq> /var/log/messages/:
cmd.run:
\- unless: echo \(aqfoo\(aq > /tmp/.test && rm \-f /tmp/.test
.ft P
@@ -295766,7 +306672,7 @@ touch /tmp/foo:
.sp
.nf
.ft C
-echo \(aqfoo\(aq | tee /tmp/bar > /tmp/baz:
+"echo \(aqfoo\(aq | tee /tmp/bar > /tmp/baz":
cmd.run:
\- creates:
\- /tmp/bar
@@ -295793,7 +306699,7 @@ In situations like this try the following:
.ft C
run_installer:
cmd.run:
- \- name: /tmp/installer.bin > /dev/null 2>&1
+ \- name: /tmp/installer.bin > /dev/null 2>&1
.ft P
.fi
.UNINDENT
@@ -296666,6 +307572,11 @@ install\-composer:
.UNINDENT
.INDENT 0.0
.TP
+.B salt.states.composer.__virtual__()
+Only load if the composer module is available in __salt__
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.composer.installed(name, composer=None, php=None, user=None, prefer_source=None, prefer_dist=None, no_scripts=None, no_plugins=None, optimize=None, no_dev=None, quiet=False, composer_home=\(aq/root\(aq, always_check=True)
Verify that the correct versions of composer dependencies are present.
.INDENT 7.0
@@ -297416,6 +308327,11 @@ Return a set of the keys with unchanged values.
.UNINDENT
.INDENT 0.0
.TP
+.B salt.states.cyg.__virtual__()
+Only load if cyg module is available in __salt__.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.cyg.installed(name, cyg_arch=\(aqx86_64\(aq, mirrors=None)
Make sure that a package is installed.
.INDENT 7.0
@@ -297677,6 +308593,11 @@ the values in the \fBdata\fP dict must be indented four spaces instead of two.
.UNINDENT
.INDENT 0.0
.TP
+.B salt.states.debconfmod.__virtual__()
+Confirm this module is on a Debian based system
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.debconfmod.set(name, data, **kwargs)
Set debconf selections
.INDENT 7.0
@@ -297955,23 +308876,24 @@ Set parameters for iDRAC in a blade.
.INDENT 7.0
.TP
.B Parameters
+.INDENT 7.0
+.IP \(bu 2
\fBidrac_password\fP \-\- Password to use to connect to the iDRACs directly
-.UNINDENT
-.sp
(idrac_ipmi and idrac_dnsname must be set directly on the iDRAC. They
can\(aqt be set through the CMC. If this password is present, use it
instead of the CMC password)
-:param idrac_ipmi: Enable/Disable IPMI over LAN
-:param idrac_ip: Set IP address for iDRAC
-:param idrac_netmask: Set netmask for iDRAC
-:param idrac_gateway: Set gateway for iDRAC
-:param idrac_dhcp: Turn on DHCP for iDRAC (True turns on, False does nothing
-.INDENT 7.0
-.INDENT 3.5
-becaause setting a static IP will disable DHCP).
+.IP \(bu 2
+\fBidrac_ipmi\fP \-\- Enable/Disable IPMI over LAN
+.IP \(bu 2
+\fBidrac_ip\fP \-\- Set IP address for iDRAC
+.IP \(bu 2
+\fBidrac_netmask\fP \-\- Set netmask for iDRAC
+.IP \(bu 2
+\fBidrac_gateway\fP \-\- Set gateway for iDRAC
+.IP \(bu 2
+\fBidrac_dhcp\fP \-\- Turn on DHCP for iDRAC (True turns on, False does
+nothing becaause setting a static IP will disable DHCP).
.UNINDENT
-.UNINDENT
-.INDENT 7.0
.TP
.B Returns
A standard Salt changes dictionary
@@ -298322,6 +309244,11 @@ Salt.
.UNINDENT
.INDENT 0.0
.TP
+.B salt.states.docker.__virtual__()
+Only load if the docker execution module is available
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.docker.absent(name, **kwargs)
Deprecated since version 2017.7.0: This state has been moved to \fBdocker_container.absent\fP\&.
@@ -298442,6 +309369,11 @@ configure access to docker registries in Pillar data.
.UNINDENT
.INDENT 0.0
.TP
+.B salt.states.docker_container.__virtual__()
+Only load if the docker execution module is available
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.docker_container.absent(name, force=False)
Ensure that a container is absent
.INDENT 7.0
@@ -300178,6 +311110,19 @@ foo:
.B privileged
False
If \fBTrue\fP, runs the exec process with extended privileges
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+foo:
+ docker_container.running:
+ \- image: bar/baz:latest
+ \- privileged: True
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
.TP
.B publish_all_ports (or \fIpublish_all\fP)
False
@@ -300557,11 +311502,7 @@ foo:
.UNINDENT
.UNINDENT
.TP
-.B volumes (or
-.nf
-*
-.fi
-volume)
+.B volumes (or \fIvolume\fP)
List of directories to expose as volumes. Can be expressed as a
comma\-separated list or a YAML list. The below two examples are
equivalent:
@@ -300781,6 +311722,11 @@ configure access to docker registries in Pillar data.
.UNINDENT
.INDENT 0.0
.TP
+.B salt.states.docker_image.__virtual__()
+Only load if the docker execution module is available
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.docker_image.absent(name=None, images=None, force=False)
Ensure that an image is absent from the Minion. Image names can be
specified either using \fBrepo:tag\fP notation, or just the repo name (in
@@ -301022,6 +311968,11 @@ These states were moved from the \fBdocker\fP state
module (formerly called \fBdockerng\fP) in the 2017.7.0 release.
.INDENT 0.0
.TP
+.B salt.states.docker_network.__virtual__()
+Only load if the docker execution module is available
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.docker_network.absent(name, driver=None)
Ensure that a network is absent.
.INDENT 7.0
@@ -301137,6 +312088,11 @@ These states were moved from the \fBdocker\fP state
module (formerly called \fBdockerng\fP) in the 2017.7.0 release.
.INDENT 0.0
.TP
+.B salt.states.docker_volume.__virtual__()
+Only load if the docker execution module is available
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.docker_volume.absent(name, driver=None)
Ensure that a volume is absent.
.sp
@@ -301317,6 +312273,11 @@ my_network:
.UNINDENT
.INDENT 0.0
.TP
+.B salt.states.drac.__virtual__()
+Ensure the racadm command is installed
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.drac.absent(name)
Ensure a user does not exist on the Dell DRAC
.INDENT 7.0
@@ -301605,6 +312566,26 @@ Optional dict for creation parameters as per \fI\%https://www.elastic.co/guide/e
.UNINDENT
.sp
\fBExample:\fP
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+# Default settings
+mytestindex:
+ elasticsearch_index.present
+
+# Extra settings
+mytestindex2:
+ elasticsearch_index.present:
+ \- definition:
+ settings:
+ index:
+ number_of_shards: 10
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
.UNINDENT
.SS salt.states.elasticsearch_index_template
.sp
@@ -301645,6 +312626,22 @@ Required dict for creation parameters as per \fI\%https://www.elastic.co/guide/e
.UNINDENT
.sp
\fBExample:\fP
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+mytestindex2_template:
+ elasticsearch_index_template.present:
+ \- definition:
+ template: logstash\-*
+ order: 1
+ settings:
+ number_of_shards: 1
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
.UNINDENT
.SS salt.states.environ
.sp
@@ -301652,6 +312649,11 @@ Support for getting and setting the environment variables
of the current salt process.
.INDENT 0.0
.TP
+.B salt.states.environ.__virtual__()
+No dependency checks, and not renaming, just return True
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.environ.setenv(name, value, false_unsets=False, clear_all=False, update_minion=False, permanent=False)
Set the salt process environment variables.
.INDENT 7.0
@@ -301735,6 +312737,11 @@ profile:
.UNINDENT
.INDENT 0.0
.TP
+.B salt.states.eselect.__virtual__()
+Only load if the eselect module is available in __salt__
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.eselect.set(name, target, module_parameter=None, action_parameter=None)
Verify that the given module is set to the given target
.INDENT 7.0
@@ -301898,6 +312905,11 @@ Performs the same functionality as \fBrm\fP but only if a watch requisite is \fB
.UNINDENT
.INDENT 0.0
.TP
+.B salt.states.etcd_mod.__virtual__()
+Only return if python\-etcd is installed
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.etcd_mod.mod_watch(name, **kwargs)
Execute a etcd function based on a watch call requisite.
.UNINDENT
@@ -302019,6 +313031,11 @@ eth0:
.UNINDENT
.INDENT 0.0
.TP
+.B salt.states.ethtool.__virtual__()
+Provide ethtool state
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.ethtool.coalesce(name, **kwargs)
Manage coalescing settings of network device
.INDENT 7.0
@@ -302746,7 +313763,7 @@ In this example \fBfoo.conf\fP in the \fBdev\fP environment will be used instead
/etc/foo.conf:
file.managed:
\- source:
- \- salt://foo.conf?saltenv=dev
+ \- \(aqsalt://foo.conf?saltenv=dev\(aq
\- user: foo
\- group: users
\- mode: \(aq0644\(aq
@@ -302770,13 +313787,7 @@ declarations. Each item in the \fBnames\fP list receives its own individual stat
\fBname\fP and is converted into its own low\-data structure. This is a convenient
way to manage several files with similar attributes.
.sp
-There is more documentation about this feature in the
-Names declaration section of the
-.INDENT 0.0
-.INDENT 3.5
-Highstate docs\&.
-.UNINDENT
-.UNINDENT
+There is more documentation about this feature in the Names declaration section of the Highstate docs\&.
.sp
Special files can be managed via the \fBmknod\fP function. This function will
create and enforce the permissions on a special file. The function supports the
@@ -303234,12 +314245,12 @@ Gather text from multiple template files:
.ft C
/etc/motd:
file:
- \- append
- \- template: jinja
- \- sources:
- \- salt://motd/devops\-messages.tmpl
- \- salt://motd/hr\-messages.tmpl
- \- salt://motd/general\-messages.tmpl
+ \- append
+ \- template: jinja
+ \- sources:
+ \- salt://motd/devops\-messages.tmpl
+ \- salt://motd/hr\-messages.tmpl
+ \- salt://motd/general\-messages.tmpl
.ft P
.fi
.UNINDENT
@@ -304006,7 +315017,7 @@ Here\(aqs an example using the above \fBwin_*\fP parameters:
.ft C
create_config_dir:
file.directory:
- \- name: C:\econfig\e
+ \- name: \(aqC:\econfig\e\(aq
\- win_owner: Administrators
\- win_perms:
# Basic Permissions
@@ -304310,7 +315321,7 @@ md5 32
.UNINDENT
.INDENT 7.0
.TP
-\fBUsing a Source Hash File\fP
+.B \fBUsing a Source Hash File\fP
The file can contain several checksums for several files. Each line
must contain both the file name and the hash. If no file name is
matched, the first hash encountered will be used, otherwise the most
@@ -304825,7 +315836,7 @@ config checker).
\- mode: 0440
\- tmp_ext: \(aq.conf\(aq
\- contents:
- \- \(aqdescription "Salt Minion"\(aq\(aq
+ \- \(aqdescription "Salt Minion"\(aq
\- \(aqstart on started mountall\(aq
\- \(aqstop on shutdown\(aq
\- \(aqrespawn\(aq
@@ -305117,6 +316128,112 @@ Ensure that some text appears at the beginning of a file
.sp
The text will not be prepended again if it already exists in the file. You
may specify a single line of text or a list of lines to append.
+.INDENT 7.0
+.TP
+.B name
+The location of the file to append to.
+.TP
+.B text
+The text to be appended, which can be a single string or a list
+of strings.
+.TP
+.B makedirs
+If the file is located in a path without a parent directory,
+then the state will fail. If makedirs is set to True, then
+the parent directories will be created to facilitate the
+creation of the named file. Defaults to False.
+.TP
+.B source
+A single source file to append. This source file can be hosted on either
+the salt master server, or on an HTTP or FTP server. Both HTTPS and
+HTTP are supported as well as downloading directly from Amazon S3
+compatible URLs with both pre\-configured and automatic IAM credentials
+(see s3.get state documentation). File retrieval from Openstack Swift
+object storage is supported via swift://container/object_path URLs
+(see swift.get documentation).
+.sp
+For files hosted on the salt file server, if the file is located on
+the master in the directory named spam, and is called eggs, the source
+string is salt://spam/eggs.
+.sp
+If the file is hosted on an HTTP or FTP server, the source_hash argument
+is also required.
+.TP
+.B source_hash
+.INDENT 7.0
+.TP
+.B This can be one of the following:
+.INDENT 7.0
+.IP 1. 3
+a source hash string
+.IP 2. 3
+the URI of a file that contains source hash strings
+.UNINDENT
+.UNINDENT
+.sp
+The function accepts the first encountered long unbroken alphanumeric
+string of correct length as a valid hash, in order from most secure to
+least secure:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+Type Length
+====== ======
+sha512 128
+sha384 96
+sha256 64
+sha224 56
+sha1 40
+md5 32
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+See the \fBsource_hash\fP parameter description for \fI\%file.managed\fP function for more details and examples.
+.TP
+.B template
+The named templating engine will be used to render the appended\-to file.
+Defaults to \fBjinja\fP\&. The following templates are supported:
+.INDENT 7.0
+.IP \(bu 2
+\fBcheetah\fP
+.IP \(bu 2
+\fBgenshi\fP
+.IP \(bu 2
+\fBjinja\fP
+.IP \(bu 2
+\fBmako\fP
+.IP \(bu 2
+\fBpy\fP
+.IP \(bu 2
+\fBwempy\fP
+.UNINDENT
+.TP
+.B sources
+A list of source files to append. If the files are hosted on an HTTP or
+FTP server, the source_hashes argument is also required.
+.TP
+.B source_hashes
+A list of source_hashes corresponding to the sources list specified in
+the sources argument.
+.TP
+.B defaults
+Default context passed to the template.
+.TP
+.B context
+Overrides default context variables passed to the template.
+.TP
+.B ignore_whitespace
+New in version 2015.8.4.
+
+.sp
+Spaces and Tabs in text are ignored by default, when searching for the
+appending content, one space or multiple tabs are the same for salt.
+Set this option to \fBFalse\fP if you want to change this behavior.
+.UNINDENT
.sp
Multi\-line example:
.INDENT 7.0
@@ -305178,12 +316295,12 @@ Gather text from multiple template files:
.ft C
/etc/motd:
file:
- \- prepend
- \- template: jinja
- \- sources:
- \- salt://motd/devops\-messages.tmpl
- \- salt://motd/hr\-messages.tmpl
- \- salt://motd/general\-messages.tmpl
+ \- prepend
+ \- template: jinja
+ \- sources:
+ \- salt://motd/devops\-messages.tmpl
+ \- salt://motd/hr\-messages.tmpl
+ \- salt://motd/general\-messages.tmpl
.ft P
.fi
.UNINDENT
@@ -305194,7 +316311,7 @@ New in version 2014.7.0.
.UNINDENT
.INDENT 0.0
.TP
-.B salt.states.file.recurse(name, source, keep_source=True, clean=False, require=None, user=None, group=None, dir_mode=None, file_mode=None, sym_mode=None, template=None, context=None, defaults=None, include_empty=False, backup=\(aq\(aq, include_pat=None, exclude_pat=None, maxdepth=None, keep_symlinks=False, force_symlinks=False, **kwargs)
+.B salt.states.file.recurse(name, source, keep_source=True, clean=False, require=None, user=None, group=None, dir_mode=None, file_mode=None, sym_mode=None, template=None, context=None, defaults=None, include_empty=False, backup=\(aq\(aq, include_pat=None, exclude_pat=None, maxdepth=None, keep_symlinks=False, force_symlinks=False, win_owner=None, win_perms=None, win_deny_perms=None, win_inheritance=True, **kwargs)
Recurse through a subdirectory on the master and copy said subdirectory
over to the specified path.
.INDENT 7.0
@@ -305390,6 +316507,36 @@ Force symlink creation. This option will force the symlink creation.
If a file or directory is obstructing symlink creation it will be
recursively removed so that symlink creation can proceed. This
option is usually not needed except in special circumstances.
+.TP
+.B win_owner
+None
+The owner of the symlink and directories if \fBmakedirs\fP is True. If
+this is not passed, \fBuser\fP will be used. If \fBuser\fP is not passed,
+the account under which Salt is running will be used.
+.sp
+New in version 2017.7.7.
+
+.TP
+.B win_perms
+None
+A dictionary containing permissions to grant
+.sp
+New in version 2017.7.7.
+
+.TP
+.B win_deny_perms
+None
+A dictionary containing permissions to deny
+.sp
+New in version 2017.7.7.
+
+.TP
+.B win_inheritance
+None
+True to inherit permissions from parent, otherwise False
+.sp
+New in version 2017.7.7.
+
.UNINDENT
.UNINDENT
.INDENT 0.0
@@ -305459,9 +316606,10 @@ If count is a positive integer n, no more than n occurrences will be
replaced, otherwise all occurrences will be replaced.
.TP
.B flags
-A list of flags defined in the \fI\%re module documentation\fP\&. Each list item should be a string that will
+A list of flags defined in the \fBre\fP module documentation from the
+Python standard library. Each list item should be a string that will
correlate to the human\-friendly flag name. E.g., \fB[\(aqIGNORECASE\(aq,
-\(aqMULTILINE\(aq]\fP\&. Optionally, \fBflags\fP may be an int, with a value
+\(aqMULTILINE\(aq]\fP\&. Optionally, \fBflags\fP may be an int, with a value
corresponding to the XOR (\fB|\fP) of all the desired flags. Defaults to
\fB8\fP (which equates to \fB[\(aqMULTILINE\(aq]\fP).
.sp
@@ -305553,7 +316701,7 @@ complex_search_and_replace:
file.replace:
# <...snip...>
\- pattern: |
- CentOS \e(2.6.32[^\en]+\en\es+root[^\en]+\en\e)+
+ CentOS \e(2.6.32[^\e\en]+\e\en\es+root[^\e\en]+\e\en\e)+
.ft P
.fi
.UNINDENT
@@ -305759,8 +316907,8 @@ For example, this state:
description: A package using naive versioning
author: A confused individual
dependencies:
- express: >= 1.2.0
- optimist: >= 0.1.0
+ express: \(aq>= 1.2.0\(aq
+ optimist: \(aq>= 0.1.0\(aq
engine: node 0.4.1
\- formatter: json
.ft P
@@ -305849,7 +316997,7 @@ process. For existing files and directories it\(aqs not enforced.
.UNINDENT
.INDENT 0.0
.TP
-.B salt.states.file.symlink(name, target, force=False, backupname=None, makedirs=False, user=None, group=None, mode=None, **kwargs)
+.B salt.states.file.symlink(name, target, force=False, backupname=None, makedirs=False, user=None, group=None, mode=None, win_owner=None, win_perms=None, win_deny_perms=None, win_inheritance=None, **kwargs)
Create a symbolic link (symlink, soft link)
.sp
If the file already exists and is a symlink pointing to any location other
@@ -305897,6 +317045,36 @@ on Windows.
.sp
The default mode for new files and directories corresponds umask of salt
process. For existing files and directories it\(aqs not enforced.
+.TP
+.B win_owner
+None
+The owner of the symlink and directories if \fBmakedirs\fP is True. If
+this is not passed, \fBuser\fP will be used. If \fBuser\fP is not passed,
+the account under which Salt is running will be used.
+.sp
+New in version 2017.7.7.
+
+.TP
+.B win_perms
+None
+A dictionary containing permissions to grant
+.sp
+New in version 2017.7.7.
+
+.TP
+.B win_deny_perms
+None
+A dictionary containing permissions to deny
+.sp
+New in version 2017.7.7.
+
+.TP
+.B win_inheritance
+None
+True to inherit permissions from parent, otherwise False
+.sp
+New in version 2017.7.7.
+
.UNINDENT
.UNINDENT
.INDENT 0.0
@@ -306002,6 +317180,11 @@ State to check firewall configurations
.. versionadded:: 2016.3.0
.INDENT 0.0
.TP
+.B salt.states.firewall.__virtual__()
+Load only if network is loaded
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.firewall.check(name, port=None, **kwargs)
Checks if there is an open connection from the minion to the defined
host on a specific port.
@@ -306013,11 +317196,7 @@ host name or ip address to test connection to
.B port
The port to test the connection on
.TP
-.B
-.nf
-**
-.fi
-kwargs
+.B kwargs
.INDENT 7.0
.TP
.B Additional parameters, parameters allowed are:
@@ -306161,6 +317340,11 @@ Returns a pretty dictionary meant for command line output.
.UNINDENT
.INDENT 0.0
.TP
+.B salt.states.firewalld.__virtual__()
+Ensure the firewall\-cmd is available
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.firewalld.present(name, block_icmp=None, default=None, masquerade=False, ports=None, port_fwd=None, services=None, prune_services=True, interfaces=None, sources=None, rich_rules=None)
Ensure a zone has specific attributes.
.UNINDENT
@@ -306194,6 +317378,11 @@ addressable:
.UNINDENT
.INDENT 0.0
.TP
+.B salt.states.gem.__virtual__()
+Only load if gem module is available in __salt__
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.gem.installed(name, ruby=None, gem_bin=None, user=None, version=None, rdoc=False, ri=False, pre_releases=False, proxy=None, source=None)
Make sure that a gem is installed.
.INDENT 7.0
@@ -306322,6 +317511,11 @@ your \fB~/.ssh/known_hosts\fP file.
Changed in version 2015.8.8: This state module now requires git 1.6.5 (released 10 October 2009) or
newer.
+.INDENT 0.0
+.TP
+.B salt.states.git.__virtual__()
+Only load if git is available
+.UNINDENT
.INDENT 0.0
.TP
.B salt.states.git.config_set(name, value=None, multivar=None, repo=None, user=None, password=None, **kwargs)
@@ -306523,7 +317717,7 @@ New in version 2016.3.0.
.sp
Make sure a repository is cloned to the given target directory and is
-a detached HEAD checkout of the commit ID resolved from \fBref\fP\&.
+a detached HEAD checkout of the commit ID resolved from \fBrev\fP\&.
.INDENT 7.0
.TP
.B name
@@ -307052,11 +318246,7 @@ if a bare repo is not desired.
.TP
.B template
If a new repository is initialized, this argument will specify an
-alternate
-.nf
-\(gatemplate directory\(ga_
-.fi
-
+alternate template directory.
.sp
New in version 2015.8.0.
@@ -307118,6 +318308,11 @@ ensure user test is present in github:
.UNINDENT
.INDENT 0.0
.TP
+.B salt.states.github.__virtual__()
+Only load if the github module is available in __salt__
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.github.absent(name, profile=\(aqgithub\(aq, **kwargs)
Ensure a github user is absent
.INDENT 7.0
@@ -307359,6 +318554,11 @@ New in version 2016.11.0.
.SS Managing Images in OpenStack Glance
.INDENT 0.0
.TP
+.B salt.states.glance.__virtual__()
+Only load if dependencies are loaded
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.glance.image_present(name, visibility=\(aqpublic\(aq, protected=None, checksum=None, location=None, disk_format=\(aqraw\(aq, wait_for=None, timeout=30)
Checks if given image is present with properties
set as specified.
@@ -307394,6 +318594,11 @@ disk_format (\(aqraw\(aq (default), \(aqvhd\(aq, \(aqvhdx\(aq, \(aqvmdk\(aq, \(a
Manage GlusterFS pool.
.INDENT 0.0
.TP
+.B salt.states.glusterfs.__virtual__()
+Only load this module if the gluster command exists
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.glusterfs.add_volume_bricks(name, bricks)
Add brick(s) to an existing volume
.INDENT 7.0
@@ -307793,6 +318998,11 @@ they exist in dashboards. The module will not manage rows that are not defined,
allowing users to manage their own custom rows.
.INDENT 0.0
.TP
+.B salt.states.grafana.__virtual__()
+Only load if grafana is available.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.grafana.dashboard_absent(name, hosts=None, profile=\(aqgrafana\(aq)
Ensure the named grafana dashboard is deleted.
.INDENT 7.0
@@ -307911,6 +319121,11 @@ Ensure minimum dashboard is managed:
.UNINDENT
.INDENT 0.0
.TP
+.B salt.states.grafana4_dashboard.__virtual__()
+Only load if grafana4 module is available
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.grafana4_dashboard.absent(name, orgname=None, profile=\(aqgrafana\(aq)
Ensure the named grafana dashboard is absent.
.INDENT 7.0
@@ -308023,6 +319238,11 @@ Ensure influxdb data source is present:
.UNINDENT
.INDENT 0.0
.TP
+.B salt.states.grafana4_datasource.__virtual__()
+Only load if grafana4 module is available
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.grafana4_datasource.absent(name, orgname=None, profile=\(aqgrafana\(aq)
Ensure that a data source is present.
.INDENT 7.0
@@ -308163,6 +319383,11 @@ Ensure foobar org is present:
.UNINDENT
.INDENT 0.0
.TP
+.B salt.states.grafana4_org.__virtual__()
+Only load if grafana4 module is available
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.grafana4_org.absent(name, profile=\(aqgrafana\(aq)
Ensure that a org is present.
.INDENT 7.0
@@ -308186,11 +319411,16 @@ Name of the org.
.TP
.B users
Optional \- Dict of user/role associated with the org. Example:
-users:
.INDENT 7.0
.INDENT 3.5
-foo: Viewer
-bar: Editor
+.sp
+.nf
+.ft C
+users:
+ foo: Viewer
+ bar: Editor
+.ft P
+.fi
.UNINDENT
.UNINDENT
.TP
@@ -308288,6 +319518,11 @@ Ensure foobar user is present:
.UNINDENT
.INDENT 0.0
.TP
+.B salt.states.grafana4_user.__virtual__()
+Only load if grafana4 module is available
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.grafana4_user.absent(name, profile=\(aqgrafana\(aq)
Ensure that a user is present.
.INDENT 7.0
@@ -308381,6 +319616,11 @@ they exist in dashboards. The module will not manage rows that are not defined,
allowing users to manage their own custom rows.
.INDENT 0.0
.TP
+.B salt.states.grafana_dashboard.__virtual__()
+Only load if grafana v2.0 is configured.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.grafana_dashboard.absent(name, profile=\(aqgrafana\(aq)
Ensure the named grafana dashboard is absent.
.INDENT 7.0
@@ -308457,6 +319697,11 @@ Ensure influxdb data source is present:
.UNINDENT
.INDENT 0.0
.TP
+.B salt.states.grafana_datasource.__virtual__()
+Only load if grafana v2.0 is configured.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.grafana_datasource.absent(name, profile=\(aqgrafana\(aq)
Ensure that a data source is present.
.INDENT 7.0
@@ -308556,7 +319801,7 @@ not be removed unless the \fIforce\fP parameter is True.
.nf
.ft C
grain_name:
- grains.absent: []
+ grains.absent
.ft P
.fi
.UNINDENT
@@ -308782,7 +320027,7 @@ nested_grain_with_complex_value:
with,a,custom,delimiter:
grains.present:
\- value: yay
- \- delimiter: ,
+ \- delimiter: \(aq,\(aq
.ft P
.fi
.UNINDENT
@@ -308971,6 +320216,11 @@ New in version 2017.7.5,2018.3.1: The spelling mistake in parameter \fIenviromen
The misspelled version is still supported for backward compatibility, but will
be removed in Salt Neon.
+.INDENT 0.0
+.TP
+.B salt.states.heat.__virtual__()
+Only load if the mysql module is in __salt__
+.UNINDENT
.INDENT 0.0
.TP
.B salt.states.heat.absent(name, poll=5, timeout=60, profile=None)
@@ -309046,6 +320296,11 @@ https://bitbucket.org/example_user/example_repo:
.UNINDENT
.INDENT 0.0
.TP
+.B salt.states.hg.__virtual__()
+Only load if hg is available
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.hg.latest(name, rev=None, target=None, clean=False, user=None, identity=None, force=False, opts=False, update_head=True)
Make sure the repository is cloned to the given directory and is up to date
.INDENT 7.0
@@ -309129,6 +320384,11 @@ hipchat:
.UNINDENT
.INDENT 0.0
.TP
+.B salt.states.hipchat.__virtual__()
+Only load if the hipchat module is available in __salt__
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.hipchat.send_message(name, room_id, from_name, message, api_url=None, api_key=None, api_version=None, message_color=\(aqyellow\(aq, notify=False)
Send a message to a Hipchat room.
.INDENT 7.0
@@ -309351,6 +320611,11 @@ username:
.UNINDENT
.INDENT 0.0
.TP
+.B salt.states.htpasswd.__virtual__()
+depends on webutil module
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.htpasswd.user_absent(name, htpasswd_file=None, runas=None)
Make sure the user is not in the specified htpasswd file
.INDENT 7.0
@@ -309517,6 +320782,11 @@ command_id:
.UNINDENT
.INDENT 0.0
.TP
+.B salt.states.icinga2.__virtual__()
+Only load if the icinga2 module is available in __salt__
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.icinga2.generate_cert(name)
Generate an icinga2 certificate and key on the client.
.INDENT 7.0
@@ -309634,6 +320904,11 @@ secret_key: bzMRb\-KKIAaNOwKEEw792J7Eb\-B3z7muhdhYblJn4V6
.UNINDENT
.INDENT 0.0
.TP
+.B salt.states.ifttt.__virtual__()
+Only load if the ifttt module is available in __salt__
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.ifttt.trigger_event(name, event, value1=None, value2=None, value3=None)
Trigger an event in IFTTT
.INDENT 7.0
@@ -309785,6 +321060,11 @@ The cmd that should be executed
.sp
New in version 2014.7.0.
+.INDENT 0.0
+.TP
+.B salt.states.influxdb08_database.__virtual__()
+Only load if the influxdb08 module is available
+.UNINDENT
.INDENT 0.0
.TP
.B salt.states.influxdb08_database.absent(name, user=None, password=None, host=None, port=None)
@@ -309836,6 +321116,11 @@ The port to connect to
.sp
New in version 2014.7.0.
+.INDENT 0.0
+.TP
+.B salt.states.influxdb08_user.__virtual__()
+Only load if the influxdb08 module is available
+.UNINDENT
.INDENT 0.0
.TP
.B salt.states.influxdb08_user.absent(name, database=None, user=None, password=None, host=None, port=None)
@@ -309898,6 +321183,11 @@ New in version 2017.7.0.
(compatible with InfluxDB version 0.9+)
.INDENT 0.0
.TP
+.B salt.states.influxdb_continuous_query.__virtual__()
+Only load if the influxdb module is available
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.influxdb_continuous_query.absent(name, database, **client_args)
Ensure that given continuous query is absent.
.INDENT 7.0
@@ -309939,6 +321229,11 @@ Duration specifying time period per sample.
(compatible with InfluxDB version 0.9+)
.INDENT 0.0
.TP
+.B salt.states.influxdb_database.__virtual__()
+Only load if the influxdb module is available
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.influxdb_database.absent(name, **client_args)
Ensure that given database is absent.
.INDENT 7.0
@@ -309966,6 +321261,11 @@ New in version 2017.7.0.
(compatible with InfluxDB version 0.9+)
.INDENT 0.0
.TP
+.B salt.states.influxdb_retention_policy.__virtual__()
+Only load if the influxdb module is available
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.influxdb_retention_policy.absent(name, database, **client_args)
Ensure that given retention policy is absent.
.INDENT 7.0
@@ -309996,6 +321296,11 @@ Database to create retention policy on.
(compatible with InfluxDB version 0.9+)
.INDENT 0.0
.TP
+.B salt.states.influxdb_user.__virtual__()
+Only load if the influxdb module is available
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.influxdb_user.absent(name, **client_args)
Ensure that given user is absent.
.INDENT 7.0
@@ -310033,6 +321338,23 @@ bar_db: all
.UNINDENT
.sp
\fBExample:\fP
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+example user present in influxdb:
+ influxdb_user.present:
+ \- name: example
+ \- password: somepassword
+ \- admin: False
+ \- grants:
+ foo_db: read
+ bar_db: all
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
.UNINDENT
.SS salt.states.infoblox module
.sp
@@ -310042,6 +321364,11 @@ ensures a record is either present or absent in an Infoblox DNS system
.sp
New in version 2016.3.0.
+.INDENT 0.0
+.TP
+.B salt.states.infoblox.__virtual__()
+make sure the infoblox module is available
+.UNINDENT
.INDENT 0.0
.TP
.B salt.states.infoblox.absent(name, record_type, dns_view, infoblox_server=None, infoblox_user=None, infoblox_password=None, infoblox_api_version=\(aqv1.4.2\(aq, sslVerify=True)
@@ -310153,6 +321480,11 @@ all
.UNINDENT
.INDENT 0.0
.TP
+.B salt.states.ini_manage.__virtual__()
+Only load if the ini module is available
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.ini_manage.options_absent(name, sections=None, separator=\(aq=\(aq)
.INDENT 7.0
.INDENT 3.5
@@ -310551,6 +321883,11 @@ setname:
.UNINDENT
.INDENT 0.0
.TP
+.B salt.states.ipset.__virtual__()
+Only load if the ipset module is available in __salt__
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.ipset.absent(name, entry=None, entries=None, family=\(aqipv4\(aq, **kwargs)
New in version 2014.7.0.
@@ -310890,6 +322227,11 @@ releases of \fBiptables\fP\&.
.UNINDENT
.INDENT 0.0
.TP
+.B salt.states.iptables.__virtual__()
+Only load if the locale module is available in __salt__
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.iptables.append(name, table=\(aqfilter\(aq, family=\(aqipv4\(aq, **kwargs)
New in version 0.17.0.
@@ -311569,60 +322911,52 @@ Install the mentioned config:
.UNINDENT
.INDENT 7.0
.TP
-.B Parameters
-.INDENT 7.0
-.IP \(bu 2
-\fBRequired\fP \-\- .INDENT 2.0
-.IP \(bu 2
-name:
-Path where the configuration/template file is present. If the file has a \(aq\fI\&.conf\(aq extension,
-the content is treated as text format. If the file has a \(aq\fP\&.xml\(aq extension,
-the content is treated as XML format. If the file has a \(aq
-.nf
-*
-.fi
-\&.set\(aq extension,
-the content is treated as Junos OS \(aqset\(aq commands.(default = None)
-.UNINDENT
-
-.IP \(bu 2
-\fBOptional\fP \-\- .INDENT 2.0
-.IP \(bu 2
-.INDENT 2.0
+.B name
+Path where the configuration/template file is present. If the file has
+a \fB*.conf\fP extension, the content is treated as text format. If the
+file has a \fB*.xml\fP extension, the content is treated as XML format. If
+the file has a \fB*.set\fP extension, the content is treated as Junos OS
+\fBset\fP commands
.TP
-.B kwargs: Keyworded arguments which can be provided like\-
-.INDENT 7.0
-.IP \(bu 2
-template_vars:
-The dictionary of data for the jinja variables present in the jinja template
-.IP \(bu 2
-timeout:
-Set NETCONF RPC timeout. Can be used for commands which
-take a while to execute. (default = 30 seconds)
-.IP \(bu 2
-overwrite:
-Set to True if you want this file is to completely replace the configuration file. (default = False)
-.IP \(bu 2
-replace:
-Specify whether the configuration file uses "replace:" statements.
-Those statements under the \(aqreplace\(aq tag will only be changed. (default = False)
-.IP \(bu 2
-comment:
+.B template_vars
+The dictionary of data for the jinja variables present in the jinja
+template
+.TP
+.B timeout
+30
+Set NETCONF RPC timeout. Can be used for commands which take a while to
+execute.
+.TP
+.B overwrite
+False.INDENT 7.0
+.TP
+.B Set to \fBTrue\fP if you want this file is to completely replace the
+configuration file.
+.UNINDENT
+.TP
+.B replace
+False
+Specify whether the configuration file uses "replace:" statements. Only
+those statements under the \(aqreplace\(aq tag will be changed.
+.TP
+.B comment
Provide a comment to the commit. (default = None)
-.IP \(bu 2
-confirm:
-Provide time in minutes for commit confirmation.
-If this option is specified, the commit will be rollbacked in the given time unless the commit is confirmed.
-.IP \(bu 2
-diffs_file:
-Path to the file where the diff (difference in old configuration
-and the committed configuration) will be stored.(default = None)
-Note that the file will be stored on the proxy minion. To push the
-files to the master use the salt\(aqs following execution module: \fBcp.push\fP
+.TP
+.B confirm
+Provide time in minutes for commit confirmation. If this option is
+specified, the commit will be rolled back in the given time unless the
+commit is confirmed.
+.TP
+.B diffs_file
+Path to the file where the diff (difference in old configuration and the
+committed configuration) will be stored.
+.sp
+\fBNOTE:\fP
+.INDENT 7.0
+.INDENT 3.5
+The file will be stored on the proxy minion. To push the files to the
+master use \fBcp.push\fP\&.
.UNINDENT
-.UNINDENT
-.UNINDENT
-
.UNINDENT
.UNINDENT
.UNINDENT
@@ -311715,62 +323049,43 @@ Install the mentioned config:
.UNINDENT
.INDENT 7.0
.TP
-.B Parameters
-.INDENT 7.0
-.IP \(bu 2
-\fBRequired\fP \-\- .INDENT 2.0
-.IP \(bu 2
-name:
-Path where the configuration/template file is present. If the file has a \(aq\fI\&.conf\(aq extension,
-the content is treated as text format. If the file has a \(aq\fP\&.xml\(aq extension,
-the content is treated as XML format. If the file has a \(aq
-.nf
-*
-.fi
-\&.set\(aq extension,
-the content is treated as Junos OS \(aqset\(aq commands.(default = None)
-.UNINDENT
-
-.IP \(bu 2
-\fBOptional\fP \-\- .INDENT 2.0
-.IP \(bu 2
-.INDENT 2.0
+.B name
+Path where the configuration/template file is present. If the file has
+a \fB*.conf\fP extension, the content is treated as text format. If the
+file has a \fB*.xml\fP extension, the content is treated as XML format. If
+the file has a \fB*.set\fP extension, the content is treated as Junos OS
+\fBset\fP commands.
.TP
-.B kwargs: Keyworded arguments which can be provided like\-
-.INDENT 7.0
-.IP \(bu 2
-overwrite:
-Set to True if you want this file is to completely replace the configuration file. (default = False)
-.IP \(bu 2
-replace:
+.B overwrite
+False
+Set to \fBTrue\fP if you want this file is to completely replace the
+configuration file.
+.TP
+.B replace
+False
Specify whether the configuration file uses "replace:" statements.
-Those statements under the \(aqreplace\(aq tag will only be changed. (default = False)
-.IP \(bu 2
-format:
+Only those statements under the \(aqreplace\(aq tag will be changed.
+.TP
+.B format:
Determines the format of the contents.
-.IP \(bu 2
-update:
-Compare a complete loaded configuration against
-the candidate configuration. For each hierarchy level or
-configuration object that is different in the two configurations,
-the version in the loaded configuration replaces the version in the
-candidate configuration. When the configuration is later committed,
-only system processes that are affected by the changed configuration
-elements parse the new configuration. This action is supported from
-PyEZ 2.1 (default = False)
-.IP \(bu 2
-template_vars:
+.TP
+.B update
+False
+Compare a complete loaded configuration against the candidate
+configuration. For each hierarchy level or configuration object that is
+different in the two configurations, the version in the loaded
+configuration replaces the version in the candidate configuration. When
+the configuration is later committed, only system processes that are
+affected by the changed configuration elements parse the new
+configuration. This action is supported from PyEZ 2.1 (default = False)
+.TP
+.B template_vars
Variables to be passed into the template processing engine in addition
to those present in __pillar__, __opts__, __grains__, etc.
You may reference these variables in your template like so:
{{ template_vars["var_name"] }}
.UNINDENT
.UNINDENT
-.UNINDENT
-
-.UNINDENT
-.UNINDENT
-.UNINDENT
.INDENT 0.0
.TP
.B salt.states.junos.lock(name)
@@ -312072,6 +323387,11 @@ kube_label_3:
.UNINDENT
.INDENT 0.0
.TP
+.B salt.states.k8s.__virtual__()
+Load only if kubernetes module is available.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.k8s.label_absent(name, node=None, apiserver=None)
Deprecated since version 2017.7.0: This state has been moved to \fBkubernetes.node_label_absent
\(ga
-.fi
-
+Anthony Shaw <\fI\%anthonyshaw@apache.org\fP>
.UNINDENT
.UNINDENT
.UNINDENT
@@ -313546,6 +324887,11 @@ root:
.UNINDENT
.INDENT 0.0
.TP
+.B salt.states.linux_acl.__virtual__()
+Ensure getfacl & setfacl exist
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.linux_acl.absent(name, acl_type, acl_name=\(aq\(aq, perms=\(aq\(aq, recurse=False)
Ensure a Linux ACL does not exist
.UNINDENT
@@ -313578,6 +324924,11 @@ default_locale:
.UNINDENT
.INDENT 0.0
.TP
+.B salt.states.locale.__virtual__()
+Only load if the locale module is available in __salt__
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.locale.present(name)
Generate a locale if it is not present
.sp
@@ -313606,6 +324957,11 @@ Module for managing logrotate.
.sp
New in version 2017.7.0.
+.INDENT 0.0
+.TP
+.B salt.states.logrotate.__virtual__()
+Load only on minions that have the logrotate module.
+.UNINDENT
.INDENT 0.0
.TP
.B salt.states.logrotate.set(name, key, value, setting=None, conf_file=\(aq/etc/logrotate.conf\(aq)
@@ -313749,6 +325105,11 @@ lvroot:
.UNINDENT
.INDENT 0.0
.TP
+.B salt.states.lvm.__virtual__()
+Only load the module if lvm is installed
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.lvm.lv_absent(name, vgname=None)
Remove a given existing logical volume from a named existing volume group
.INDENT 7.0
@@ -313855,6 +325216,11 @@ Any supported options to vgcreate. See
.SS Management of LVS (Linux Virtual Server) Real Server
.INDENT 0.0
.TP
+.B salt.states.lvs_server.__virtual__()
+Only load if the lvs module is available in __salt__
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.lvs_server.absent(name, protocol=None, service_address=None, server_address=None)
Ensure the LVS Real Server in specified service is absent.
.INDENT 7.0
@@ -313917,6 +325283,11 @@ lvsrs:
.SS Management of LVS (Linux Virtual Server) Service
.INDENT 0.0
.TP
+.B salt.states.lvs_service.__virtual__()
+Only load if the lvs module is available in __salt__
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.lvs_service.absent(name, protocol=None, service_address=None)
Ensure the LVS service is absent.
.INDENT 7.0
@@ -314384,6 +325755,11 @@ Install, enable and disable assistive access on macOS minions
.UNINDENT
.INDENT 0.0
.TP
+.B salt.states.mac_assistive.__virtual__()
+Only work on Mac OS
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.mac_assistive.installed(name, enabled=True)
Make sure that we have the given bundle ID or path to command
installed in the assistive access panel.
@@ -314400,6 +325776,11 @@ Should assistive access be enabled on this application?
.SS Writing/reading defaults from a macOS minion
.INDENT 0.0
.TP
+.B salt.states.mac_defaults.__virtual__()
+Only work on Mac OS
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.mac_defaults.absent(name, domain, user=None)
Make sure the defaults value is absent
.INDENT 7.0
@@ -314455,6 +325836,11 @@ Install certificats to the macOS keychain
.UNINDENT
.INDENT 0.0
.TP
+.B salt.states.mac_keychain.__virtual__()
+Only work on Mac OS
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.mac_keychain.default_keychain(name, domain=\(aquser\(aq, user=None)
Set the default keychain to use
.INDENT 7.0
@@ -314539,17 +325925,20 @@ Install any kind of pkg, dmg or app file on macOS:
\- dmg: True
/mnt/xcode.dmg:
- macpackage.installed:
- \- dmg: True
- \- app: True
- \- target: /Applications/Xcode.app
- \- version_check: xcodebuild \-version=Xcode 7.1
+ macpackage.installed:
+ \- dmg: True
+ \- app: True
+ \- target: /Applications/Xcode.app
+ \- version_check: xcodebuild \-version=Xcode 7.1\en.*7B91b
.ft P
.fi
.UNINDENT
.UNINDENT
-.sp
-\&.*7B91b
+.INDENT 0.0
+.TP
+.B salt.states.mac_package.__virtual__()
+Only work on Mac OS
+.UNINDENT
.INDENT 0.0
.TP
.B salt.states.mac_package.installed(name, target=\(aqLocalSystem\(aq, dmg=False, store=False, app=False, mpkg=False, user=None, onlyif=None, unless=None, force=False, allow_untrusted=False, version_check=None)
@@ -314595,6 +325984,16 @@ Allow the installation of untrusted packages
.TP
.B version_check
The command and version that we want to check against, the version number can use regex.
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+version_check: python \-\-version_check=2.7.[0\-9]
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
.UNINDENT
.UNINDENT
.SS salt.states.mac_xattr module
@@ -314617,6 +326016,11 @@ Install, enable and disable assistive access on macOS minions
.UNINDENT
.INDENT 0.0
.TP
+.B salt.states.mac_xattr.__virtual__()
+Only work on Mac OS
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.mac_xattr.delete(name, attributes)
Make sure the given attributes are deleted from the file/directory
.INDENT 7.0
@@ -314662,6 +326066,11 @@ makeopts:
.UNINDENT
.INDENT 0.0
.TP
+.B salt.states.makeconf.__virtual__()
+Only load if the makeconf module is available in __salt__
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.makeconf.absent(name)
Verify that the variable is not in the \fBmake.conf\fP\&.
.INDENT 7.0
@@ -314791,6 +326200,11 @@ A state module for creating or destroying software RAID devices.
.UNINDENT
.INDENT 0.0
.TP
+.B salt.states.mdadm.__virtual__()
+mdadm provides raid functions for Linux
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.mdadm.absent(name)
Verify that the raid is absent
.INDENT 7.0
@@ -314858,6 +326272,11 @@ Example:
.sp
New in version 2014.1.0.
+.INDENT 0.0
+.TP
+.B salt.states.memcached.__virtual__()
+Only load if memcache module is available
+.UNINDENT
.INDENT 0.0
.TP
.B salt.states.memcached.absent(name, value=None, host=\(aq127.0.0.1\(aq, port=11211, time=0)
@@ -314930,6 +326349,11 @@ foo:
State to control Apache modjk
.INDENT 0.0
.TP
+.B salt.states.modjk.__virtual__()
+Load this state if modjk is loaded
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.modjk.worker_activated(name, workers=None, profile=\(aqdefault\(aq)
Activate all the workers in the modjk load balancer
.sp
@@ -315033,6 +326457,11 @@ execution module \fBdocumentation\fP
.UNINDENT
.INDENT 0.0
.TP
+.B salt.states.modjk_worker.__virtual__()
+Check if we have peer access ?
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.modjk_worker.activate(name, lbn, target, profile=\(aqdefault\(aq, tgt_type=\(aqglob\(aq, expr_form=None)
Changed in version 2017.7.0: The \fBexpr_form\fP argument has been renamed to \fBtgt_type\fP, earlier
releases must use \fBexpr_form\fP\&.
@@ -315574,6 +327003,11 @@ execution module is available.
.UNINDENT
.INDENT 0.0
.TP
+.B salt.states.monit.__virtual__()
+Only make this state available if the monit module is available.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.monit.monitor(name)
Get the summary from module monit and try to see if service is
being monitored. If not then monitor the service.
@@ -315832,79 +327266,71 @@ running as on the minion
.SS Send a message card to Microsoft Teams
.sp
This state is useful for sending messages to Teams during state runs.
-.. versionadded:: 2017.7.0
-.. code\-block:: yaml
+.sp
+New in version 2017.7.0.
+
.INDENT 0.0
.INDENT 3.5
-.INDENT 0.0
-.TP
-.B teams\-message:
-.INDENT 7.0
-.TP
-.B msteams.post_card:
-.INDENT 7.0
-.IP \(bu 2
-message: \(aqThis state was executed successfully.\(aq
-.IP \(bu 2
-hook_url: \fI\%https://outlook.office.com/webhook/837\fP
-.UNINDENT
-.UNINDENT
-.UNINDENT
+.sp
+.nf
+.ft C
+teams\-message:
+ msteams.post_card:
+ \- message: \(aqThis state was executed successfully.\(aq
+ \- hook_url: https://outlook.office.com/webhook/837
+.ft P
+.fi
.UNINDENT
.UNINDENT
.sp
The hook_url can be specified in the master or minion configuration like below:
-.. code\-block:: yaml
.INDENT 0.0
.INDENT 3.5
+.sp
+.nf
+.ft C
+msteams:
+ hook_url: https://outlook.office.com/webhook/837
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
.INDENT 0.0
.TP
-.B msteams:
-hook_url: \fI\%https://outlook.office.com/webhook/837\fP
-.UNINDENT
-.UNINDENT
+.B salt.states.msteams.__virtual__()
+Only load if the msteams module is available in __salt__
.UNINDENT
.INDENT 0.0
.TP
.B salt.states.msteams.post_card(name, message, hook_url=None, title=None, theme_color=None)
-Send a message to a Microsft Teams channel.
-.. code\-block:: yaml
+Send a message to a Microsft Teams channel
.INDENT 7.0
.INDENT 3.5
-.INDENT 0.0
-.TP
-.B send\-msteams\-message:
-.INDENT 7.0
-.TP
-.B msteams.post_card:
-.INDENT 7.0
-.IP \(bu 2
-message: \(aqThis state was executed successfully.\(aq
-.IP \(bu 2
-hook_url: \fI\%https://outlook.office.com/webhook/837\fP
-.UNINDENT
-.UNINDENT
-.UNINDENT
+.sp
+.nf
+.ft C
+send\-msteams\-message:
+ msteams.post_card:
+ \- message: \(aqThis state was executed successfully.\(aq
+ \- hook_url: https://outlook.office.com/webhook/837
+.ft P
+.fi
.UNINDENT
.UNINDENT
.sp
The following parameters are required:
-message
.INDENT 7.0
-.INDENT 3.5
+.TP
+.B message
The message that is to be sent to the MS Teams channel.
.UNINDENT
-.UNINDENT
.sp
The following parameters are optional:
-hook_url
.INDENT 7.0
-.INDENT 3.5
+.TP
+.B hook_url
The webhook URL given configured in Teams interface,
if not specified in the configuration options of master or minion.
-.UNINDENT
-.UNINDENT
-.INDENT 7.0
.TP
.B title
The title for the card posted to the channel
@@ -315942,6 +327368,11 @@ frank:
.UNINDENT
.INDENT 0.0
.TP
+.B salt.states.mysql_database.__virtual__()
+Only load if the mysql module is available in __salt__
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.mysql_database.absent(name, **connection_args)
Ensure that the named database is absent
.INDENT 7.0
@@ -316026,6 +327457,11 @@ restricted_singletable:
.UNINDENT
.INDENT 0.0
.TP
+.B salt.states.mysql_grants.__virtual__()
+Only load if the mysql module is available
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.mysql_grants.absent(name, grant=None, database=None, user=None, host=\(aqlocalhost\(aq, grant_option=False, escape=True, **connection_args)
Ensure that the grant is absent
.INDENT 7.0
@@ -316153,6 +327589,11 @@ query_id:
.UNINDENT
.INDENT 0.0
.TP
+.B salt.states.mysql_query.__virtual__()
+Only load if the mysql module is available in __salt__
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.mysql_query.run(name, database, query, output=None, grain=None, key=None, overwrite=True, **connection_args)
Execute an arbitrary query on the specified database
.INDENT 7.0
@@ -316184,8 +327625,11 @@ The file or grain will be overwritten if it already exists (default)
.UNINDENT
.INDENT 0.0
.TP
-.B salt.states.mysql_query.run_file(name, database, query_file=None, output=None, grain=None, key=None, overwrite=True, **connection_args)
+.B salt.states.mysql_query.run_file(name, database, query_file=None, output=None, grain=None, key=None, overwrite=True, saltenv=None, **connection_args)
Execute an arbitrary query on the specified database
+.sp
+New in version 2017.7.0.
+
.INDENT 7.0
.TP
.B name
@@ -316211,10 +327655,10 @@ of this state will be stored under the specified key.
.TP
.B overwrite:
The file or grain will be overwritten if it already exists (default)
+.TP
+.B saltenv:
+The saltenv to pull the query_file from
.UNINDENT
-.sp
-New in version 2017.7.0.
-
.UNINDENT
.SS salt.states.mysql_user
.SS Management of MySQL users
@@ -316274,6 +327718,11 @@ This state is not able to grant permissions for the user. See
\fBsalt.states.mysql_grants\fP for further instructions.
.INDENT 0.0
.TP
+.B salt.states.mysql_user.__virtual__()
+Only load if the mysql module is in __salt__
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.mysql_user.absent(name, host=\(aqlocalhost\(aq, **connection_args)
Ensure that the named user is absent
.INDENT 7.0
@@ -316364,6 +327813,11 @@ it requires \fI\%NAPALM\fP library to be installed: \fBpip install napalm\fP\&.
Please check \fI\%Installation\fP for complete details.
.INDENT 0.0
.TP
+.B salt.states.netacl.__virtual__()
+This module requires both NAPALM and Capirca.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.netacl.filter(name, filter_name, filter_options=None, terms=None, prepend=True, pillar_key=\(aqacl\(aq, pillarenv=None, saltenv=None, merge_pillar=False, only_lower_merge=False, revision_id=None, revision_no=None, revision_date=True, revision_date_format=\(aq%Y/%m/%d\(aq, test=False, commit=True, debug=False)
Generate and load the configuration of a policy filter.
.INDENT 7.0
@@ -316686,7 +328140,7 @@ Output Example:
.nf
.ft C
edge01.bjm01:
- \-\-\-\-\-\-\-\-\-\-
+\-\-\-\-\-\-\-\-\-\-\-\-\-
ID: netacl_example
Function: netacl.managed
Result: None
@@ -316968,18 +328422,10 @@ A special service to choose from. This is a helper so the user is able to
select a source just using the name, instead of specifying a destination_port and protocol.
Allows the same options as \fBsource_service\fP\&.
.TP
-.B
-.nf
-**
-.fi
-term_fields
-Term attributes.
-To see what fields are supported, please consult the list of supported \fI\%keywords\fP\&.
-.INDENT 7.0
-.INDENT 3.5
-Some platforms have few other \fI\%optional\fP keywords.
-.UNINDENT
-.UNINDENT
+.B term_fields
+Term attributes. To see what fields are supported, please consult the
+list of supported \fI\%keywords\fP\&. Some platforms have few other \fI\%optional\fP
+keywords.
.UNINDENT
.sp
\fBNOTE:\fP
@@ -317225,8 +328671,9 @@ source_service:
\fBNOTE:\fP
.INDENT 7.0
.INDENT 3.5
-The port fields \fBsource_port\fP and \fBdestination_port\fP can be used as above to select either
-a single value, either a list of values, but also they can select port ranges. Example:
+The port fields \fBsource_port\fP and \fBdestination_port\fP can be used as
+above to select either a single value, either a list of values, but
+also they can select port ranges. Example:
.INDENT 0.0
.INDENT 3.5
.sp
@@ -317409,6 +328856,11 @@ unix
.sp
New in version 2017.7.0.
+.INDENT 0.0
+.TP
+.B salt.states.netconfig.__virtual__()
+NAPALM library must be installed for this module to work and run in a (proxy) minion.
+.UNINDENT
.INDENT 0.0
.TP
.B salt.states.netconfig.managed(name, template_name, template_source=None, template_path=None, template_hash=None, template_hash_name=None, template_user=\(aqroot\(aq, template_group=\(aqroot\(aq, template_mode=\(aq755\(aq, saltenv=None, template_engine=\(aqjinja\(aq, skip_verify=False, defaults=None, test=False, commit=True, debug=False, replace=False, **template_vars)
@@ -317538,9 +328990,10 @@ result after the template was rendered.
.INDENT 7.0
.INDENT 3.5
This argument cannot be used directly on the command line. Instead,
-it can be passed through the \fBpillar\fP variable when executing one
-of the salt.modules.state.sls or salt.modules.state.apply
-functions (see an example below).
+it can be passed through the \fBpillar\fP variable when executing
+either of the \fBstate.sls\fP or
+\fBstate.apply\fP (see below for an
+example).
.UNINDENT
.UNINDENT
.TP
@@ -317550,11 +329003,7 @@ Load and replace the configuration. Default: \fBFalse\fP (will apply load merge)
.B defaults: None
Default variables/context passed to the template.
.TP
-.B
-.nf
-**
-.fi
-template_vars
+.B template_vars
Dictionary with the arguments/context to be used when the template is rendered. Do not explicitly specify this
argument. This represents any other variable that will be sent to the template rendering system. Please
see an example below! In both \fBntp_peers_example_using_pillar\fP and \fBntp_peers_example\fP, \fBpeers\fP is sent as
@@ -317659,6 +329108,15 @@ Raw output example (useful when the output is reused in other states/execution m
.nf
.ft C
$ sudo salt \-\-out=pprint \(aqjuniper.device\(aq state.sls router.config test=True debug=True
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
{
\(aqjuniper.device\(aq: {
\(aqnetconfig_|\-ntp_peers_example_using_pillar_|\-ntp_peers_example_using_pillar_|\-managed\(aq: {
@@ -317703,14 +329161,22 @@ unix
.SS Dependencies
.INDENT 0.0
.IP \(bu 2
-Requires \fI\%netaddr\fP to be installed: \fIpip install netaddr\fP to check if IP Addresses are correctly specified
+Requires \fI\%netaddr\fP to be installed: \fIpip install netaddr\fP to check if IP
+Addresses are correctly specified
.IP \(bu 2
-Requires \fI\%dnspython\fP to be installed: \fIpip install dnspython\fP to resolve the nameserver entities
+Requires \fI\%dnspython\fP to be installed: \fIpip install dnspython\fP to resolve the
+nameserver entities (in case the user does not configure the peers/servers
+using their IP addresses)
+.IP \(bu 2
+\fBNAPALM proxy minion\fP
+.IP \(bu 2
+\fBNTP operational and configuration management module\fP
+.UNINDENT
+.INDENT 0.0
+.TP
+.B salt.states.netntp.__virtual__()
+NAPALM library must be installed for this module to work and run in a (proxy) minion.
.UNINDENT
-.sp
-(in case the user does not configure the peers/servers using their IP addresses)
-\- \fBNAPALM proxy minion\fP
-\- \fBNTP operational and configuration management module\fP
.INDENT 0.0
.TP
.B salt.states.netntp.managed(name, peers=None, servers=None)
@@ -317795,6 +329261,11 @@ unix
.UNINDENT
.INDENT 0.0
.TP
+.B salt.states.netsnmp.__virtual__()
+NAPALM library must be installed for this module to work and run in a (proxy) minion.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.netsnmp.managed(name, config=None, defaults=None)
Configures the SNMP on the device as specified in the SLS file.
.sp
@@ -317881,6 +329352,11 @@ unix
.sp
New in version 2016.11.0.
+.INDENT 0.0
+.TP
+.B salt.states.netusers.__virtual__()
+NAPALM library must be installed for this module to work and run in a (proxy) minion.
+.UNINDENT
.INDENT 0.0
.TP
.B salt.states.netusers.managed(name, users=None, defaults=None)
@@ -318323,6 +329799,12 @@ ports argument is required. Red Hat systems will ignore the argument.
.UNINDENT
.INDENT 0.0
.TP
+.B salt.states.network.__virtual__()
+Confine this module to non\-Windows systems with the required execution
+module available.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.network.managed(name, type, enabled=True, **kwargs)
Ensure that the named interface is configured properly.
.INDENT 7.0
@@ -318387,8 +329869,14 @@ it requires \fI\%NAPALM\fP library to be installed: \fBpip install napalm\fP\&.
Please check \fI\%Installation\fP for complete details.
.INDENT 0.0
.TP
+.B salt.states.netyang.__virtual__()
+NAPALM library must be installed for this module to work and run in a (proxy) minion.
+This module in particular requires also napalm\-yang.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.netyang.configured(name, data, models, **kwargs)
-Configure the network device, given the input data strucuted
+Configure the network device, given the input data structured
according to the YANG models.
.sp
\fBNOTE:\fP
@@ -318660,6 +330148,11 @@ httpd:
.UNINDENT
.INDENT 0.0
.TP
+.B salt.states.nftables.__virtual__()
+Only load if the locale module is available in __salt__
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.nftables.append(name, family=\(aqipv4\(aq, **kwargs)
New in version 0.17.0.
@@ -318794,6 +330287,11 @@ yaml:
.UNINDENT
.INDENT 0.0
.TP
+.B salt.states.npm.__virtual__()
+Only load if the npm module is available in __salt__
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.npm.bootstrap(name, user=None, silent=True)
Bootstraps a node.js application.
.sp
@@ -318932,6 +330430,11 @@ win_ntp:
.UNINDENT
.INDENT 0.0
.TP
+.B salt.states.ntp.__virtual__()
+This only supports Windows
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.ntp.managed(name, servers=None)
Manage NTP servers
.INDENT 7.0
@@ -319163,6 +330666,11 @@ linux
.UNINDENT
.INDENT 0.0
.TP
+.B salt.states.openstack_config.__virtual__()
+Only load if the openstack_config module is in __salt__
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.openstack_config.absent(name, filename, section, parameter=None)
Ensure a value is not set in an OpenStack configuration file.
.INDENT 7.0
@@ -319201,6 +330709,11 @@ The value to set
Management of Open vSwitch bridges.
.INDENT 0.0
.TP
+.B salt.states.openvswitch_bridge.__virtual__()
+Only make these states available if Open vSwitch module is available.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.openvswitch_bridge.absent(name)
Ensures that the named bridge does not exist, eventually deletes it.
.INDENT 7.0
@@ -319224,6 +330737,11 @@ Ensures that the named bridge exists, eventually creates it.
Management of Open vSwitch ports.
.INDENT 0.0
.TP
+.B salt.states.openvswitch_port.__virtual__()
+Only make these states available if Open vSwitch module is available.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.openvswitch_port.absent(name, bridge=None)
Ensures that the named port exists on bridge, eventually deletes it.
If bridge is not set, port is removed from whatever bridge contains it.
@@ -319288,6 +330806,11 @@ server\-warning\-message:
.UNINDENT
.INDENT 0.0
.TP
+.B salt.states.pagerduty.__virtual__()
+Only load if the pygerduty module is available in __salt__
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.pagerduty.create_event(name, details, service_key, profile)
Create an event on the PagerDuty service
.INDENT 7.0
@@ -319365,6 +330888,11 @@ ensure test escalation policy:
.UNINDENT
.INDENT 0.0
.TP
+.B salt.states.pagerduty_escalation_policy.__virtual__()
+Only load if the pygerduty module is available in __salt__
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.pagerduty_escalation_policy.absent(profile=\(aqpagerduty\(aq, subdomain=None, api_key=None, **kwargs)
Ensure that a PagerDuty escalation policy does not exist.
Accepts all the arguments that pagerduty_escalation_policy.present accepts;
@@ -319426,87 +330954,46 @@ PagerDuty id (usually a 7 digit all\-caps string, e.g. PX6GQL7)
.SS salt.states.pagerduty_schedule
.sp
Manage PagerDuty schedules.
-Example.INDENT 0.0
+.sp
+Example:
+.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
-
+ensure test schedule:
+ pagerduty_schedule.present:
+ \- name: \(aqbruce test schedule level1\(aq
+ \- schedule:
+ name: \(aqbruce test schedule level1\(aq
+ time_zone: \(aqPacific Time (US & Canada)\(aq
+ schedule_layers:
+ \- name: \(aqSchedule Layer 1\(aq
+ start: \(aq2015\-01\-01T00:00:00\(aq
+ users:
+ \- user:
+ \(aqid\(aq: \(aqBruce TestUser1\(aq
+ member_order: 1
+ \- user:
+ \(aqid\(aq: \(aqBruce TestUser2\(aq
+ member_order: 2
+ \- user:
+ \(aqid\(aq: \(aqbruce+test3@lyft.com\(aq
+ member_order: 3
+ \- user:
+ \(aqid\(aq: \(aqbruce+test4@lyft.com\(aq
+ member_order: 4
+ rotation_virtual_start: \(aq2015\-01\-01T00:00:00\(aq
+ priority: 1
+ rotation_turn_length_seconds: 604800
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
-.B ensure test schedule:
-.INDENT 7.0
-.TP
-.B pagerduty_schedule.present:
-.INDENT 7.0
-.IP \(bu 2
-name: \(aqbruce test schedule level1\(aq
-.IP \(bu 2
-.INDENT 2.0
-.TP
-.B schedule:
-name: \(aqbruce test schedule level1\(aq
-time_zone: \(aqPacific Time (US & Canada)\(aq
-schedule_layers:
-.INDENT 7.0
-.INDENT 3.5
-.INDENT 0.0
-.IP \(bu 2
-name: \(aqSchedule Layer 1\(aq
-start: \(aq2015\-01\-01T00:00:00\(aq
-users:
-.INDENT 2.0
-.INDENT 3.5
-.INDENT 0.0
-.IP \(bu 2
-.INDENT 2.0
-.TP
-.B user:
-\(aqid\(aq: \(aqBruce TestUser1\(aq
-.UNINDENT
-.sp
-member_order: 1
-.IP \(bu 2
-.INDENT 2.0
-.TP
-.B user:
-\(aqid\(aq: \(aqBruce TestUser2\(aq
-.UNINDENT
-.sp
-member_order: 2
-.IP \(bu 2
-.INDENT 2.0
-.TP
-.B user:
-\(aqid\(aq: \fI\%\(aqbruce+test3@lyft.com\fP\(aq
-.UNINDENT
-.sp
-member_order: 3
-.IP \(bu 2
-.INDENT 2.0
-.TP
-.B user:
-\(aqid\(aq: \fI\%\(aqbruce+test4@lyft.com\fP\(aq
-.UNINDENT
-.sp
-member_order: 4
-.UNINDENT
-.UNINDENT
-.UNINDENT
-.sp
-rotation_virtual_start: \(aq2015\-01\-01T00:00:00\(aq
-priority: 1
-rotation_turn_length_seconds: 604800
-.UNINDENT
-.UNINDENT
-.UNINDENT
-.UNINDENT
-.UNINDENT
-.UNINDENT
+.B salt.states.pagerduty_schedule.__virtual__()
+Only load if the pygerduty module is available in __salt__
.UNINDENT
.INDENT 0.0
.TP
@@ -319533,35 +331020,22 @@ Escalation policies can be referenced by pagerduty ID or by namea.
For example:
.INDENT 0.0
.INDENT 3.5
-.INDENT 0.0
-.INDENT 3.5
.sp
.nf
.ft C
-
+ensure test service
+ pagerduty_service.present:
+ \- name: \(aqmy service\(aq
+ \- escalation_policy_id: \(aqmy escalation policy\(aq
+ \- type: nagios
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
-.B ensure test service
-.INDENT 7.0
-.TP
-.B pagerduty_service.present:
-.INDENT 7.0
-.IP \(bu 2
-name: \(aqmy service\(aq
-.IP \(bu 2
-escalation_policy_id: \(aqmy escalation policy\(aq
-.IP \(bu 2
-type: nagios
-.UNINDENT
-.sp
-[etc]
-.UNINDENT
-.UNINDENT
-.UNINDENT
+.B salt.states.pagerduty_service.__virtual__()
+Only load if the pygerduty module is available in __salt__
.UNINDENT
.INDENT 0.0
.TP
@@ -319584,61 +331058,37 @@ Examples:
.sp
.nf
.ft C
-
+# create a PagerDuty email service at test\-email@DOMAIN.pagerduty.com
+ensure generic email service exists:
+ pagerduty_service.present:
+ \- name: my email service
+ \- service:
+ description: "email service controlled by salt"
+ escalation_policy_id: "my escalation policy"
+ type: "generic_email"
+ service_key: "test\-email"
.ft P
.fi
.UNINDENT
.UNINDENT
-.sp
-# create a PagerDuty email service at \fI\%test\-email@DOMAIN.pagerduty.com\fP
-ensure generic email service exists:
.INDENT 7.0
.INDENT 3.5
-.INDENT 0.0
-.TP
-.B pagerduty_service.present:
-.INDENT 7.0
-.IP \(bu 2
-name: my email service
-.IP \(bu 2
-.INDENT 2.0
-.TP
-.B service:
-description: "email service controlled by salt"
-escalation_policy_id: "my escalation policy"
-type: "generic_email"
-service_key: "test\-email"
-.UNINDENT
-.UNINDENT
-.UNINDENT
-.UNINDENT
-.UNINDENT
.sp
+.nf
+.ft C
# create a pagerduty service using cloudwatch integration
ensure my cloudwatch service exists:
-.INDENT 7.0
-.INDENT 3.5
-.INDENT 0.0
-.TP
-.B pagerduty_service.present:
-.INDENT 7.0
-.IP \(bu 2
-name: my cloudwatch service
-.IP \(bu 2
-.INDENT 2.0
-.TP
-.B service:
-escalation_policy_id: "my escalation policy"
-type: aws_cloudwatch
-description: "my cloudwatch service controlled by salt"
+ pagerduty_service.present:
+ \- name: my cloudwatch service
+ \- service:
+ escalation_policy_id: "my escalation policy"
+ type: aws_cloudwatch
+ description: "my cloudwatch service controlled by salt"
+.ft P
+.fi
.UNINDENT
.UNINDENT
.UNINDENT
-.UNINDENT
-.UNINDENT
-.sp
-TODO: aws_cloudwatch type should be integrated with boto_sns
-.UNINDENT
.SS salt.states.pagerduty_user
.sp
Manage PagerDuty users.
@@ -319670,6 +331120,11 @@ requester_id: P1GV5NT
.UNINDENT
.INDENT 0.0
.TP
+.B salt.states.pagerduty_user.__virtual__()
+Only load if the pygerduty module is available in __salt__
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.pagerduty_user.absent(profile=\(aqpagerduty\(aq, subdomain=None, api_key=None, **kwargs)
Ensure pagerduty user does not exist.
Name can be pagerduty id, email address, or user name.
@@ -319917,6 +331372,11 @@ haproxy_pcs__constraint_present_colocation\-vip_galera\-haproxy\-clone\-INFINITY
.sp
New in version 2016.3.0.
+.INDENT 0.0
+.TP
+.B salt.states.pcs.__virtual__()
+Only load if pcs package is installed
+.UNINDENT
.INDENT 0.0
.TP
.B salt.states.pcs.auth(name, nodes, pcsuser=\(aqhacluster\(aq, pcspasswd=\(aqhacluster\(aq, extra_args=None)
@@ -320403,6 +331863,11 @@ mongo:
.UNINDENT
.INDENT 0.0
.TP
+.B salt.states.pecl.__virtual__()
+Only load if the pecl module is available in __salt__
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.pecl.installed(name, version=None, defaults=False, force=False, preferred_state=\(aqstable\(aq)
New in version 0.17.0.
@@ -320479,6 +331944,11 @@ kaylee:
.UNINDENT
.INDENT 0.0
.TP
+.B salt.states.pdbedit.__virtual__()
+Provides pdbedit when available
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.pdbedit.absent(name)
Ensure user account is absent
.INDENT 7.0
@@ -320597,6 +332067,11 @@ virtualenvwrapper:
.UNINDENT
.INDENT 0.0
.TP
+.B salt.states.pip_state.__virtual__()
+Only load if the pip module is available in __salt__
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.pip_state.installed(name, pkgs=None, pip_bin=None, requirements=None, bin_env=None, use_wheel=False, no_use_wheel=False, log=None, proxy=None, timeout=None, repo=None, editable=None, find_links=None, index_url=None, extra_index_url=None, no_index=False, mirrors=None, build=None, target=None, download=None, download_cache=None, source=None, upgrade=False, force_reinstall=False, ignore_installed=False, exists_action=None, no_deps=False, no_install=False, no_download=False, install_options=None, global_options=None, user=None, cwd=None, pre_releases=False, cert=None, allow_all_external=False, allow_external=None, allow_unverified=None, process_dependency_links=False, env_vars=None, use_vt=False, trusted_host=None, no_cache_dir=False, cache_dir=None, no_binary=None, **kwargs)
Make sure the package is installed
.INDENT 7.0
@@ -321061,6 +332536,12 @@ used. This will be addressed in a future release of Salt.
.UNINDENT
.INDENT 0.0
.TP
+.B salt.states.pkg.__virtual__()
+Only make these states available if a pkg provider has been detected or
+assigned for this minion
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.pkg.downloaded(name, version=None, pkgs=None, fromrepo=None, ignore_epoch=None, **kwargs)
New in version 2017.7.0.
@@ -322928,6 +334409,11 @@ installed if it is not present.
.UNINDENT
.INDENT 0.0
.TP
+.B salt.states.pkgrepo.__virtual__()
+Only load if modifying repos is available for this package type
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.pkgrepo.absent(name, **kwargs)
This function deletes the specified repo on the system, if it exists. It
is essentially a wrapper around pkg.del_repo.
@@ -323243,6 +334729,11 @@ salt:
.UNINDENT
.INDENT 0.0
.TP
+.B salt.states.portage_config.__virtual__()
+Only load if the portage_config module is available in __salt__
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.portage_config.flags(name, use=None, accept_keywords=None, env=None, license=None, properties=None, unmask=False, mask=False)
Enforce the given flags on the given package or \fBDEPEND\fP atom.
.sp
@@ -323366,6 +334857,11 @@ create cluster 9.3 main:
.UNINDENT
.INDENT 0.0
.TP
+.B salt.states.postgres_cluster.__virtual__()
+Only load if the deb_postgres module is present
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.postgres_cluster.absent(version, name)
Ensure that the named cluster is absent
.INDENT 7.0
@@ -323427,6 +334923,11 @@ frank:
.UNINDENT
.INDENT 0.0
.TP
+.B salt.states.postgres_database.__virtual__()
+Only load if the postgres module is present
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.postgres_database.absent(name, user=None, maintenance_db=None, db_password=None, db_host=None, db_port=None, db_user=None)
Ensure that the named database is absent
.INDENT 7.0
@@ -323521,6 +335022,11 @@ adminpack:
.sp
New in version 2014.7.0.
+.INDENT 0.0
+.TP
+.B salt.states.postgres_extension.__virtual__()
+Only load if the postgres module is present
+.UNINDENT
.INDENT 0.0
.TP
.B salt.states.postgres_extension.absent(name, if_exists=None, restrict=None, cascade=None, user=None, maintenance_db=None, db_user=None, db_password=None, db_host=None, db_port=None)
@@ -323626,6 +335132,11 @@ frank:
.UNINDENT
.INDENT 0.0
.TP
+.B salt.states.postgres_group.__virtual__()
+Only load if the postgres module is present
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.postgres_group.absent(name, user=None, maintenance_db=None, db_password=None, db_host=None, db_port=None, db_user=None)
Ensure that the named group is absent
.INDENT 7.0
@@ -323768,6 +335279,11 @@ pgsql\-data\-dir:
.UNINDENT
.INDENT 0.0
.TP
+.B salt.states.postgres_initdb.__virtual__()
+Only load if the postgres module is present
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.postgres_initdb.present(name, user=None, password=None, auth=\(aqpassword\(aq, encoding=\(aqUTF8\(aq, locale=None, runas=None)
Initialize the PostgreSQL data directory
.INDENT 7.0
@@ -323828,6 +335344,11 @@ plpgsql:
.UNINDENT
.INDENT 0.0
.TP
+.B salt.states.postgres_language.__virtual__()
+Only load if the postgres module is present
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.postgres_language.absent(name, maintenance_db, user=None, db_password=None, db_host=None, db_port=None, db_user=None)
Ensure that a named language is absent in the specified
database.
@@ -323982,6 +335503,11 @@ andrew:
.UNINDENT
.INDENT 0.0
.TP
+.B salt.states.postgres_privileges.__virtual__()
+Only load if the postgres module is present
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.postgres_privileges.absent(name, object_name, object_type, privileges=None, prepend=\(aqpublic\(aq, maintenance_db=None, user=None, db_password=None, db_host=None, db_port=None, db_user=None)
Revoke the requested privilege(s) on the specificed object(s)
.INDENT 7.0
@@ -324186,6 +335712,11 @@ public:
.UNINDENT
.INDENT 0.0
.TP
+.B salt.states.postgres_schema.__virtual__()
+Only load if the postgres module is present
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.postgres_schema.absent(dbname, name, db_user=None, db_password=None, db_host=None, db_port=None)
Ensure that the named schema is absent.
.INDENT 7.0
@@ -324257,6 +335788,11 @@ ssd\-tablespace:
.sp
New in version 2015.8.0.
+.INDENT 0.0
+.TP
+.B salt.states.postgres_tablespace.__virtual__()
+Only load if the postgres module is present and is new enough (has ts funcs)
+.UNINDENT
.INDENT 0.0
.TP
.B salt.states.postgres_tablespace.absent(name, user=None, maintenance_db=None, db_user=None, db_password=None, db_host=None, db_port=None)
@@ -324289,12 +335825,8 @@ Database port if different from config or default
.TP
.B salt.states.postgres_tablespace.present(name, directory, options=None, owner=None, user=None, maintenance_db=None, db_password=None, db_host=None, db_port=None, db_user=None)
Ensure that the named tablespace is present with the specified properties.
-For more information about all of these options see man
-
-.nf
-\(ga\(ga
-.fi
-create_tablespace\(ga\(ga(7).
+For more information about all of these options run \fBman 7
+create_tablespace\fP\&.
.INDENT 7.0
.TP
.B name
@@ -324363,6 +335895,11 @@ frank:
.UNINDENT
.INDENT 0.0
.TP
+.B salt.states.postgres_user.__virtual__()
+Only load if the postgres module is present
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.postgres_user.absent(name, user=None, maintenance_db=None, db_password=None, db_host=None, db_port=None, db_user=None)
Ensure that the named user is absent
.INDENT 7.0
@@ -324546,18 +336083,27 @@ unix
.UNINDENT
.INDENT 0.0
.TP
+.B salt.states.probes.__virtual__()
+NAPALM library must be installed for this module to work and run in a (proxy) minion.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.probes.managed(name, probes, defaults=None)
Ensure the networks device is configured as specified in the state SLS file.
Probes not specified will be removed, while probes not confiured as expected will trigger config updates.
.INDENT 7.0
.TP
.B Parameters
-\fBprobes\fP \-\- Defines the probes as expected to be configured on the device.
+.INDENT 7.0
+.IP \(bu 2
+\fBprobes\fP \-\- Defines the probes as expected to be configured on the
+device. In order to ease the configuration and avoid repeating the
+same parameters for each probe, the next parameter (defaults) can be
+used, providing common characteristics.
+.IP \(bu 2
+\fBdefaults\fP \-\- Specifies common parameters for the probes.
+.UNINDENT
.UNINDENT
-.sp
-In order to ease the configuration and avoid repeating the same parameters for each probe,
-the next parameter (defaults) can be used, providing common characteristics.
-:param defaults: Specifies common parameters for the probes.
.sp
SLS Example:
.INDENT 7.0
@@ -324596,22 +336142,19 @@ dictionary). All the other parameters will use the operating system
defaults, if not provided:
.INDENT 7.0
.IP \(bu 2
+\fBsource\fP \- Specifies the source IP Address to be used during the tests. If
+not specified will use the IP Address of the logical interface loopback0.
+.IP \(bu 2
+\fBtarget\fP \- Destination IP Address.
+.IP \(bu 2
+\fBprobe_count\fP \- Total number of probes per test (1..15). System
+defaults: 1 on both JunOS & Cisco.
+.IP \(bu 2
+\fBprobe_interval\fP \- Delay between tests (0..86400 seconds). System
+defaults: 3 on JunOS, 5 on Cisco.
+.IP \(bu 2
+\fBprobe_type\fP \- Probe request type. Available options:
.INDENT 2.0
-.TP
-.B source: Specifies the source IP Address to be used during the tests.
-If not specified will use the IP Address of the logical interface loopback0.
-.UNINDENT
-.IP \(bu 2
-target: Destination IP Address.
-.IP \(bu 2
-probe_count: Total number of probes per test (1..15). System defaults: 1 on both JunOS & Cisco.
-.IP \(bu 2
-probe_interval: Delay between tests (0..86400 seconds). System defaults: 3 on JunOS, 5 on Cisco.
-.IP \(bu 2
-probe_type: Probe request type. Available options:
-.INDENT 2.0
-.INDENT 3.5
-.INDENT 0.0
.IP \(bu 2
icmp\-ping
.IP \(bu 2
@@ -324620,8 +336163,6 @@ tcp\-ping
udp\-ping
.UNINDENT
.UNINDENT
-.UNINDENT
-.UNINDENT
.sp
Using the example configuration above, after running the state, on the device will be configured 4 probes,
with the following properties:
@@ -324711,6 +336252,11 @@ Setup proxy settings on minions
.UNINDENT
.INDENT 0.0
.TP
+.B salt.states.proxy.__virtual__()
+Only work on Mac OS and Windows
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.proxy.managed(name, port, services=None, user=None, password=None, bypass_domains=None, network_service=\(aqEthernet\(aq)
Manages proxy settings for this mininon
.INDENT 7.0
@@ -324779,6 +336325,11 @@ token: peWcBiMOS9HrZG15peWcBiMOS9HrZG15
.UNINDENT
.INDENT 0.0
.TP
+.B salt.states.pushover.__virtual__()
+Only load if the pushover module is available in __salt__
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.pushover.post_message(name, user=None, device=None, message=None, title=None, priority=None, expire=None, retry=None, sound=None, api_version=1, token=None)
Send a message to a PushOver channel.
.INDENT 7.0
@@ -324983,6 +336534,11 @@ myqueue:
.UNINDENT
.INDENT 0.0
.TP
+.B salt.states.pyrax_queues.__virtual__()
+Only load if pyrax is available.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.pyrax_queues.absent(name, provider)
Ensure the named Rackspace queue is deleted.
.INDENT 7.0
@@ -325026,6 +336582,11 @@ The quota can be managed for the system:
.UNINDENT
.INDENT 0.0
.TP
+.B salt.states.quota.__virtual__()
+Only load if the quota module is available in __salt__
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.quota.mode(name, mode, quotatype)
Set the quota for the system
.INDENT 7.0
@@ -325059,6 +336620,11 @@ rabbit@rabbit.example.com:
.UNINDENT
.INDENT 0.0
.TP
+.B salt.states.rabbitmq_cluster.__virtual__()
+Only load if RabbitMQ is installed.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.rabbitmq_cluster.join(name, host, user=\(aqrabbit\(aq, ram_node=None, runas=\(aqroot\(aq)
This function is an alias of \fBjoined\fP\&.
.INDENT 7.0
@@ -325126,6 +336692,11 @@ some_plugin:
.UNINDENT
.INDENT 0.0
.TP
+.B salt.states.rabbitmq_plugin.__virtual__()
+Only load if RabbitMQ is installed.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.rabbitmq_plugin.disabled(name, runas=None)
Ensure the RabbitMQ plugin is disabled.
.INDENT 7.0
@@ -325181,6 +336752,11 @@ rabbit_policy:
.UNINDENT
.INDENT 0.0
.TP
+.B salt.states.rabbitmq_policy.__virtual__()
+Only load if RabbitMQ is installed.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.rabbitmq_policy.absent(name, vhost=\(aq/\(aq, runas=None)
Ensure the named policy is absent
.sp
@@ -325249,6 +336825,11 @@ rabbit_user:
.UNINDENT
.INDENT 0.0
.TP
+.B salt.states.rabbitmq_user.__virtual__()
+Only load if RabbitMQ is installed.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.rabbitmq_user.absent(name, runas=None)
Ensure the named user is absent
.INDENT 7.0
@@ -325306,6 +336887,11 @@ virtual_host:
.UNINDENT
.INDENT 0.0
.TP
+.B salt.states.rabbitmq_vhost.__virtual__()
+Only load if RabbitMQ is installed.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.rabbitmq_vhost.absent(name)
Ensure the RabbitMQ Virtual Host is absent
.INDENT 7.0
@@ -325368,9 +336954,7 @@ Deprecated since version 2015.8.0.
.UNINDENT
.UNINDENT
-======\-\-\-\-\-\-============
-salt.states.rbac_solaris
-========================
+.SS salt.states.rbac_solaris
.sp
Management of Solaris RBAC
.INDENT 0.0
@@ -325409,6 +336993,11 @@ sjorge:
.UNINDENT
.INDENT 0.0
.TP
+.B salt.states.rbac_solaris.__virtual__()
+Provides rbac on Solaris like platforms
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.rbac_solaris.managed(name, roles=None, profiles=None, authorizations=None)
Manage RBAC properties for user
.INDENT 7.0
@@ -325562,6 +337151,11 @@ New in version 0.16.0.
Manage RDP Service on Windows servers
.INDENT 0.0
.TP
+.B salt.states.rdp.__virtual__()
+Load only if network_win is loaded
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.rdp.disabled(name)
Disable the RDP service
.UNINDENT
@@ -325621,6 +337215,11 @@ key_in_redis:
.UNINDENT
.INDENT 0.0
.TP
+.B salt.states.redismod.__virtual__()
+Only load if the redis module is in __salt__
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.redismod.absent(name, keys=None, **connection_args)
Ensure key absent from redis
.INDENT 7.0
@@ -325691,28 +337290,40 @@ Values or Entries are the name/data pairs beneath the keys and subkeys. All keys
have a default name/data pair. It is usually "(Default)"="(value not set)". The
actual value for the name and the date is Null. The registry editor will display
"(Default)" and "(value not set)".
+Example
.sp
The following example is taken from the windows startup portion of the registry:
-\fB\(ga
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
[HKEY_LOCAL_MACHINE\eSOFTWARE\eMicrosoft\eWindows\eCurrentVersion\eRun]
"RTHDVCPL"="\e"C:\e\eProgram Files\e\eRealtek\e\eAudio\e\eHDA\e\eRtkNGUI64.exe\e" \-s"
"NvBackend"="\e"C:\e\eProgram Files (x86)\e\eNVIDIA Corporation\e\eUpdate Core\e\eNvBackend.exe\e""
"BTMTrayAgent"="rundll32.exe \e"C:\e\eProgram Files (x86)\e\eIntel\e\eBluetooth\e\ebtmshellex.dll\e",TrayApp"
-\(ga\fP
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
In this example these are the values for each:
.sp
Hive: \fIHKEY_LOCAL_MACHINE\fP
.sp
Key and subkeys: \fISOFTWAREMicrosoftWindowsCurrentVersionRun\fP
+.sp
+Value:
.INDENT 0.0
-.TP
-.B Value:
-.INDENT 7.0
.IP \(bu 2
There are 3 value names: \fIRTHDVCPL\fP, \fINvBackend\fP, and \fIBTMTrayAgent\fP
.IP \(bu 2
Each value name has a corresponding value
.UNINDENT
+.INDENT 0.0
+.TP
+.B salt.states.reg.__virtual__()
+Load this state if the reg module exists
.UNINDENT
.INDENT 0.0
.TP
@@ -325722,9 +337333,8 @@ Ensure a registry value is removed. To remove a key use key_absent.
.TP
.B Parameters
\fBname\fP (\fI\%str\fP) \-\- A string value representing the full path of the key to
-.UNINDENT
-.sp
include the HIVE, Key, and all Subkeys. For example:
+.UNINDENT
.sp
\fBHKEY_LOCAL_MACHINE\eSOFTWARE\eSalt\fP
.sp
@@ -325740,20 +337350,16 @@ HKEY_USERS or HKU
.INDENT 7.0
.TP
.B Parameters
+.INDENT 7.0
+.IP \(bu 2
\fBvname\fP (\fI\%str\fP) \-\- The name of the value you\(aqd like to create beneath the
-.UNINDENT
-.sp
Key. If this parameter is not passed it will assume you want to set the
(Default) value
-.INDENT 7.0
-.TP
-.B Parameters
+.IP \(bu 2
\fBuse_32bit_registry\fP (\fI\%bool\fP) \-\- Use the 32bit portion of the registry.
+Applies only to 64bit windows. 32bit Windows will ignore this
+parameter. Default is False.
.UNINDENT
-.sp
-Applies only to 64bit windows. 32bit Windows will ignore this parameter.
-Default is False.
-.INDENT 7.0
.TP
.B Returns
Returns a dictionary showing the results of the registry operation.
@@ -325792,10 +337398,9 @@ entries it contains. It will fail if the key contains subkeys.
.TP
.B Parameters
\fBname\fP (\fI\%str\fP) \-\- A string representing the full path to the key to be
-.UNINDENT
-.sp
removed to include the hive and the keypath. The hive can be any of the
following:
+.UNINDENT
.INDENT 7.0
.IP \(bu 2
HKEY_LOCAL_MACHINE or HKLM
@@ -325808,11 +337413,8 @@ HKEY_USER or HKU
.TP
.B Parameters
\fBuse_32bit_registry\fP (\fI\%bool\fP) \-\- Use the 32bit portion of the registry.
-.UNINDENT
-.sp
-Applies only to 64bit windows. 32bit Windows will ignore this parameter.
-Default is False.
-.INDENT 7.0
+Applies only to 64bit windows. 32bit Windows will ignore this
+parameter. Default is False.
.TP
.B Returns
Returns a dictionary showing the results of the registry operation.
@@ -325854,32 +337456,34 @@ Ensure a registry key or value is present.
.TP
.B Parameters
\fBname\fP (\fI\%str\fP) \-\- A string value representing the full path of the key to
-.UNINDENT
-.sp
include the HIVE, Key, and all Subkeys. For example:
+.UNINDENT
.sp
\fBHKEY_LOCAL_MACHINE\eSOFTWARE\eSalt\fP
.sp
Valid hive values include:
-\- HKEY_CURRENT_USER or HKCU
-\- HKEY_LOCAL_MACHINE or HKLM
-\- HKEY_USERS or HKU
+.INDENT 7.0
+.IP \(bu 2
+HKEY_CURRENT_USER or HKCU
+.IP \(bu 2
+HKEY_LOCAL_MACHINE or HKLM
+.IP \(bu 2
+HKEY_USERS or HKU
+.UNINDENT
.INDENT 7.0
.TP
.B Parameters
+.INDENT 7.0
+.IP \(bu 2
\fBvname\fP (\fI\%str\fP) \-\- The name of the value you\(aqd like to create beneath the
-.UNINDENT
-.sp
Key. If this parameter is not passed it will assume you want to set the
(Default) value
-.INDENT 7.0
-.TP
-.B Parameters
+.IP \(bu 2
\fBvdata\fP (\fI\%str\fP) \-\- The value you\(aqd like to set. If a value name (vname) is
+passed, this will be the data for that value name. If not, this will be
+the (Default) value for the key.
+.UNINDENT
.UNINDENT
-.sp
-passed, this will be the data for that value name. If not, this will be the
-(Default) value for the key.
.sp
The type for the (Default) value is always REG_SZ and cannot be changed.
This parameter is optional. If not passed, the Key will be created with no
@@ -325888,9 +337492,8 @@ associated item/value pairs.
.TP
.B Parameters
\fBvtype\fP (\fI\%str\fP) \-\- The value type for the data you wish to store in the
-.UNINDENT
-.sp
registry. Valid values are:
+.UNINDENT
.INDENT 7.0
.IP \(bu 2
REG_BINARY
@@ -325907,11 +337510,8 @@ REG_SZ (Default)
.TP
.B Parameters
\fBuse_32bit_registry\fP (\fI\%bool\fP) \-\- Use the 32bit portion of the registry.
-.UNINDENT
-.sp
-Applies only to 64bit windows. 32bit Windows will ignore this parameter.
-Default is False.
-.INDENT 7.0
+Applies only to 64bit windows. 32bit Windows will ignore this
+parameter. Default is False.
.TP
.B Returns
Returns a dictionary showing the results of the registry operation.
@@ -325979,6 +337579,16 @@ New in version 2016.3.0.
\- force: True
.ft P
.fi
+.UNINDENT
+.UNINDENT
+.INDENT 0.0
+.TP
+.B salt.states.rsync.__virtual__()
+Only if Rsync is available.
+.INDENT 7.0
+.TP
+.B Returns
+
.UNINDENT
.UNINDENT
.INDENT 0.0
@@ -326276,6 +337886,11 @@ Full Orchestrate Tutorial
.UNINDENT
.INDENT 0.0
.TP
+.B salt.states.saltmod.__virtual__()
+Named salt
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.saltmod.function(name, tgt, ssh=False, tgt_type=\(aqglob\(aq, expr_form=None, ret=\(aq\(aq, expect_minions=False, fail_minions=None, fail_function=None, arg=None, kwarg=None, timeout=None, batch=None, subset=None)
Execute a single module function on a remote minion via salt or salt\-ssh
.INDENT 7.0
@@ -326828,6 +338443,11 @@ execution module is available.
.UNINDENT
.INDENT 0.0
.TP
+.B salt.states.selinux.__virtual__()
+Only make this state available if the selinux module is available.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.selinux.boolean(name, value, persist=False)
Set up an SELinux boolean
.INDENT 7.0
@@ -326913,13 +338533,12 @@ The SELinux MLS range.
.B salt.states.selinux.mode(name)
Verifies the mode SELinux is running in, can be set to enforcing,
permissive, or disabled
+.sp
+\fBNOTE:\fP
.INDENT 7.0
.INDENT 3.5
-.INDENT 0.0
-.TP
-.B Note: A change to or from disabled mode requires a system reboot.
-You will need to perform this yourself.
-.UNINDENT
+A change to or from disabled mode requires a system reboot. You will
+need to perform this yourself.
.UNINDENT
.UNINDENT
.INDENT 7.0
@@ -327208,6 +338827,12 @@ Requisites documentation.
.UNINDENT
.INDENT 0.0
.TP
+.B salt.states.service.__virtual__()
+Only make these states available if a service provider has been detected or
+assigned for this minion
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.service.dead(name, enable=None, sig=None, init_delay=None, **kwargs)
Ensure that the named service is dead by stopping the service if it is running
.INDENT 7.0
@@ -327491,6 +339116,11 @@ slack:
.UNINDENT
.INDENT 0.0
.TP
+.B salt.states.slack.__virtual__()
+Only load if the slack module is available in __salt__
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.slack.post_message(name, channel, from_name, message, api_key=None, icon=None)
Send a message to a Slack channel.
.INDENT 7.0
@@ -327640,6 +339270,11 @@ The same behavior as when using \(aqvmadm update\(aq.
.UNINDENT
.INDENT 0.0
.TP
+.B salt.states.smartos.__virtual__()
+Provides smartos state provided for SmartOS
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.smartos.config_absent(name)
Ensure configuration property is absent in /usbkey/config
.INDENT 7.0
@@ -327857,6 +339492,11 @@ server\-warning\-message:
.UNINDENT
.INDENT 0.0
.TP
+.B salt.states.smtp.__virtual__()
+Only load if the SMTP module is available in __salt__
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.smtp.send_msg(name, recipient, subject, sender=None, profile=None, use_ssl=\(aqTrue\(aq)
Send a message via SMTP
.INDENT 7.0
@@ -328037,6 +339677,11 @@ Linux
.UNINDENT
.INDENT 0.0
.TP
+.B salt.states.snapper.__virtual__()
+Only load if the snapper module is available in __salt__
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.snapper.baseline_snapshot(name, number=None, tag=None, include_diff=True, config=\(aqroot\(aq, ignore=None)
Enforces that no file is modified comparing against a previously
defined snapshot identified by number.
@@ -328124,6 +339769,11 @@ ensure example test user 1:
.UNINDENT
.INDENT 0.0
.TP
+.B salt.states.splunk.__virtual__()
+Only load if the splunk module is available in __salt__
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.splunk.absent(email, profile=\(aqsplunk\(aq, **kwargs)
Ensure a splunk user is absent
.INDENT 7.0
@@ -328200,6 +339850,11 @@ server\-warning\-message:
.UNINDENT
.INDENT 0.0
.TP
+.B salt.states.splunk_search.__virtual__()
+Only load if the splunk_search module is available in __salt__
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.splunk_search.absent(name, profile=\(aqsplunk\(aq)
Ensure a search is absent
.INDENT 7.0
@@ -328248,6 +339903,9 @@ This is the name of the search in splunk
.UNINDENT
.SS salt.states.sqlite3
.SS Management of SQLite3 databases
+.sp
+New in version 2016.3.0.
+
.INDENT 0.0
.TP
.B depends
@@ -328259,9 +339917,6 @@ SQLite3 Python Module
.B configuration
See \fBsalt.modules.sqlite3\fP for setup instructions
.UNINDENT
-.sp
-New in version 2016.3.0.
-
.sp
The sqlite3 module is used to create and manage sqlite3 databases
and execute queries
@@ -328269,8 +339924,6 @@ and execute queries
Here is an example of creating a table using sql statements:
.INDENT 0.0
.INDENT 3.5
-.INDENT 0.0
-.INDENT 3.5
.sp
.nf
.ft C
@@ -328282,14 +339935,10 @@ users:
.fi
.UNINDENT
.UNINDENT
-.UNINDENT
-.UNINDENT
.sp
Here is an example of creating a table using yaml/jinja instead of sql:
.INDENT 0.0
.INDENT 3.5
-.INDENT 0.0
-.INDENT 3.5
.sp
.nf
.ft C
@@ -328307,14 +339956,10 @@ users:
.fi
.UNINDENT
.UNINDENT
-.UNINDENT
-.UNINDENT
.sp
Here is an example of making sure a table is absent:
.INDENT 0.0
.INDENT 3.5
-.INDENT 0.0
-.INDENT 3.5
.sp
.nf
.ft C
@@ -328325,15 +339970,11 @@ badservers:
.fi
.UNINDENT
.UNINDENT
-.UNINDENT
-.UNINDENT
.sp
Sometimes you would to have specific data in tables to be used by other services
Here is an example of making sure rows with specific data exist:
.INDENT 0.0
.INDENT 3.5
-.INDENT 0.0
-.INDENT 3.5
.sp
.nf
.ft C
@@ -328355,14 +339996,10 @@ user_john_doe_xyz:
.fi
.UNINDENT
.UNINDENT
-.UNINDENT
-.UNINDENT
.sp
Here is an example of removing a row from a table:
.INDENT 0.0
.INDENT 3.5
-.INDENT 0.0
-.INDENT 3.5
.sp
.nf
.ft C
@@ -328377,15 +340014,11 @@ user_john_doe_abc:
.fi
.UNINDENT
.UNINDENT
-.UNINDENT
-.UNINDENT
.sp
Note that there is no explicit state to perform random queries, however, this
can be approximated with sqlite3\(aqs module functions and module.run:
.INDENT 0.0
.INDENT 3.5
-.INDENT 0.0
-.INDENT 3.5
.sp
.nf
.ft C
@@ -328400,7 +340033,10 @@ zone\-delete:
.fi
.UNINDENT
.UNINDENT
-.UNINDENT
+.INDENT 0.0
+.TP
+.B salt.states.sqlite3.__virtual__()
+Only load if the sqlite3 module is available
.UNINDENT
.INDENT 0.0
.TP
@@ -328691,6 +340327,11 @@ example.com:
.UNINDENT
.INDENT 0.0
.TP
+.B salt.states.ssh_known_hosts.__virtual__()
+Does not work on Windows, requires ssh module functions
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.ssh_known_hosts.absent(name, user=None, config=None)
Verifies that the specified host is not known by the given user
.INDENT 7.0
@@ -328827,6 +340468,11 @@ statuspage:
.sp
New in version 2017.7.0.
+.INDENT 0.0
+.TP
+.B salt.states.statuspage.__virtual__()
+Return the execution module virtualname.
+.UNINDENT
.INDENT 0.0
.TP
.B salt.states.statuspage.create(name, endpoint=u\(aqincidents\(aq, api_url=None, page_id=None, api_key=None, api_version=None, **kwargs)
@@ -328848,11 +340494,7 @@ API version. Can also be specified in the config file.
.B api_url
Custom API URL in case the user has a StatusPage service running in a custom environment.
.TP
-.B
-.nf
-**
-.fi
-kwargs
+.B kwargs
Other params.
.UNINDENT
.sp
@@ -329012,6 +340654,11 @@ Support for Stormpath.
.sp
New in version 2015.8.0.
+.INDENT 0.0
+.TP
+.B salt.states.stormpath_account.__virtual__()
+Only load if the stormpath module is available in __salt__
+.UNINDENT
.INDENT 0.0
.TP
.B salt.states.stormpath_account.absent(name, directory_id=None)
@@ -329163,6 +340810,11 @@ http://unladen\-swallow.googlecode.com/svn/trunk/:
.UNINDENT
.INDENT 0.0
.TP
+.B salt.states.svn.__virtual__()
+Only load if svn is available
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.svn.dirty(name, target, user=None, username=None, password=None, ignore_unversioned=False)
Determine if the working directory has been changed.
.UNINDENT
@@ -329281,6 +340933,11 @@ vm.swappiness:
.UNINDENT
.INDENT 0.0
.TP
+.B salt.states.sysctl.__virtual__()
+This state is only available on Minions which support sysctl
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.sysctl.present(name, value, config=None)
Ensure that the named sysctl value is set in memory and persisted to the
named configuration file. The default sysctl configuration file is
@@ -329388,6 +341045,11 @@ Kills syslog\-ng.
.SS salt.states.sysrc
.INDENT 0.0
.TP
+.B salt.states.sysrc.__virtual__()
+Only load if sysrc executable exists
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.sysrc.absent(name, **kwargs)
Ensure a sysrc variable is absent.
.INDENT 7.0
@@ -329795,6 +341457,11 @@ it applies to systems that dual\-boot with Windows. This is explained in greater
detail \fI\%here\fP\&.
.INDENT 0.0
.TP
+.B salt.states.timezone.__virtual__()
+Only load if the timezone module is available in __salt__
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.timezone.system(name, utc=True)
Set the timezone for the system.
.INDENT 7.0
@@ -329895,6 +341562,11 @@ Linux
.UNINDENT
.INDENT 0.0
.TP
+.B salt.states.tomcat.__virtual__()
+Load if the module tomcat exists
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.tomcat.mod_watch(name, url=\(aqhttp://localhost:8080/manager\(aq, timeout=180)
The tomcat watcher function.
When called it will reload the webapp in question
@@ -330066,6 +341738,11 @@ either specify a version yourself, or set version to \fBFalse\fP\&.
.sp
New in version 2015.8.0.
+.INDENT 0.0
+.TP
+.B salt.states.trafficserver.__virtual__()
+Only load if the Traffic Server module is available in __salt__
+.UNINDENT
.INDENT 0.0
.TP
.B salt.states.trafficserver.bounce_cluster(name)
@@ -330449,6 +342126,11 @@ url/sitemap.xml:
.UNINDENT
.INDENT 0.0
.TP
+.B salt.states.uptime.__virtual__()
+Only load if the uptime module is present
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.uptime.monitored(name, **params)
Makes sure an URL is monitored by uptime. Checks if URL is already
monitored, and if not, adds it.
@@ -330734,51 +342416,20 @@ Rules formatted as in\-line HCL
.sp
.nf
.ft C
-
+demo\-policy:
+ vault.policy_present:
+ \- name: foo/bar
+ \- rules: |
+ path "secret/top\-secret/*" {
+ policy = "deny"
+ }
+ path "secret/not\-very\-secret/*" {
+ policy = "write"
+ }
.ft P
.fi
.UNINDENT
.UNINDENT
-.INDENT 7.0
-.TP
-.B demo\-policy:
-.INDENT 7.0
-.TP
-.B vault.policy_present:
-.INDENT 7.0
-.IP \(bu 2
-name: foo/bar
-.IP \(bu 2
-.INDENT 2.0
-.TP
-.B rules: |
-.INDENT 7.0
-.TP
-.B path "secret/top\-secret/
-.nf
-*
-.fi
-" {
-policy = "deny"
-.UNINDENT
-.sp
-}
-path "secret/not\-very\-secret/
-.nf
-*
-.fi
-" {
-.INDENT 7.0
-.INDENT 3.5
-policy = "write"
-.UNINDENT
-.UNINDENT
-.sp
-}
-.UNINDENT
-.UNINDENT
-.UNINDENT
-.UNINDENT
.UNINDENT
.SS salt.states.vbox_guest
.sp
@@ -330863,6 +342514,11 @@ webserver\-warning\-message:
.UNINDENT
.INDENT 0.0
.TP
+.B salt.states.victorops.__virtual__()
+Only load if the victorops module is available in __salt__
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.victorops.create_event(name, message_type, routing_key=\(aqeveryone\(aq, **kwargs)
Create an event on the VictorOps service
.INDENT 7.0
@@ -330953,6 +342609,16 @@ libvirt_keys:
virt.keys
.ft P
.fi
+.UNINDENT
+.UNINDENT
+.INDENT 0.0
+.TP
+.B salt.states.virt.__virtual__()
+Only if virt module is available.
+.INDENT 7.0
+.TP
+.B Returns
+
.UNINDENT
.UNINDENT
.INDENT 0.0
@@ -331262,6 +342928,11 @@ salt://certs/cert.cer:
.UNINDENT
.INDENT 0.0
.TP
+.B salt.states.win_certutil.__virtual__()
+Only work on Windows
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.win_certutil.add_store(name, store, saltenv=\(aqbase\(aq)
Store a certificate to the given store
.INDENT 7.0
@@ -331407,6 +343078,11 @@ dInherit:
.UNINDENT
.INDENT 0.0
.TP
+.B salt.states.win_dacl.__virtual__()
+Load this state if the win_acl module exists
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.win_dacl.absent(name, objectType, user, permission, acetype, propagation)
Ensure an ACL does not exist
.UNINDENT
@@ -331445,6 +343121,11 @@ NetFx3:
.UNINDENT
.INDENT 0.0
.TP
+.B salt.states.win_dism.__virtual__()
+Only work on Windows where the DISM module is available
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.win_dism.capability_installed(name, source=None, limit_access=False, image=None, restart=False)
Install a DISM capability
.INDENT 7.0
@@ -331687,6 +343368,11 @@ remove_KB1231231:
Module for configuring DNS Client on Windows systems
.INDENT 0.0
.TP
+.B salt.states.win_dns_client.__virtual__()
+Load if the module win_dns_client is loaded
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.win_dns_client.dns_dhcp(name, interface=\(aqLocal Area Connection\(aq)
Configure the DNS server list from DHCP Server
.UNINDENT
@@ -331749,6 +343435,11 @@ primary_dns_suffix:
State for configuring Windows Firewall
.INDENT 0.0
.TP
+.B salt.states.win_firewall.__virtual__()
+Load if the module firewall is loaded
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.win_firewall.add_rule(name, localport, protocol=\(aqtcp\(aq, action=\(aqallow\(aq, dir=\(aqin\(aq, remoteip=\(aqany\(aq)
Add a new inbound or outbound rule to the firewall policy
.INDENT 7.0
@@ -331948,6 +343639,11 @@ from Microsoft IIS.
.sp
New in version 2016.3.0.
+.INDENT 0.0
+.TP
+.B salt.states.win_iis.__virtual__()
+Load only on minions that have the win_iis module.
+.UNINDENT
.INDENT 0.0
.TP
.B salt.states.win_iis.container_setting(name, container, settings=None)
@@ -331963,10 +343659,9 @@ Set the value of the setting for an IIS container.
AppPools, Sites, SslBindings
.IP \(bu 2
\fBsettings\fP (\fI\%str\fP) \-\- A dictionary of the setting names and their values.
-.UNINDENT
-.UNINDENT
-.sp
Example of usage for the \fBAppPools\fP container:
+.UNINDENT
+.UNINDENT
.INDENT 7.0
.INDENT 3.5
.sp
@@ -332547,17 +344242,15 @@ site0\-foo\-vdir\-remove:
.INDENT 0.0
.TP
.B salt.states.win_iis.set_app(name, site, settings=None)
+New in version 2017.7.0.
+
+.sp
Set the value of the setting for an IIS web application.
-.. note:
+.sp
+\fBNOTE:\fP
.INDENT 7.0
.INDENT 3.5
-.sp
-.nf
-.ft C
-This function only configures existing app.
-Params are case sensitive.
-.ft P
-.fi
+This function only configures existing app. Params are case sensitive.
.UNINDENT
.UNINDENT
.INDENT 7.0
@@ -332571,16 +344264,25 @@ Params are case sensitive.
.IP \(bu 2
\fBsettings\fP (\fI\%str\fP) \-\- A dictionary of the setting names and their values.
.UNINDENT
-.TP
-.B Available settings
-physicalPath: The physical path of the webapp.
.UNINDENT
.sp
-: applicationPool: The application pool for the webapp.
-: userName: "connectAs" user
-: password: "connectAs" password for user
-:rtype: bool
-.. versionadded:: 2017.7.0
+Available settings:
+.INDENT 7.0
+.IP \(bu 2
+\fBphysicalPath\fP \- The physical path of the webapp
+.IP \(bu 2
+\fBapplicationPool\fP \- The application pool for the webapp
+.IP \(bu 2
+\fBuserName\fP "connectAs" user
+.IP \(bu 2
+\fBpassword\fP "connectAs" password for user
+.UNINDENT
+.INDENT 7.0
+.TP
+.B Return type
+\fI\%bool\fP
+.UNINDENT
+.sp
Example of usage:
.INDENT 7.0
.INDENT 3.5
@@ -332728,6 +344430,11 @@ server_policy:
.UNINDENT
.INDENT 0.0
.TP
+.B salt.states.win_lgpo.__virtual__()
+load this state if the win_lgpo module exists
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.win_lgpo.set(name, setting=None, policy_class=None, computer_policy=None, user_policy=None, cumulative_rights_assignments=True, adml_language=\(aqen\-US\(aq)
Ensure the specified policy is set
.INDENT 7.0
@@ -332776,6 +344483,11 @@ XXXXX\-XXXXX\-XXXXX\-XXXXX\-XXXXX:
.UNINDENT
.INDENT 0.0
.TP
+.B salt.states.win_license.__virtual__()
+Only work on Windows
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.win_license.activate(name)
Install and activate the given product key
.INDENT 7.0
@@ -332869,6 +344581,12 @@ Local Area Connection #2:
.UNINDENT
.INDENT 0.0
.TP
+.B salt.states.win_network.__virtual__()
+Confine this module to Windows systems with the required execution module
+available.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.win_network.managed(name, dns_proto=None, dns_servers=None, ip_proto=None, ip_addrs=None, gateway=None, enabled=True, **kwargs)
Ensure that the named interface is configured properly.
.INDENT 7.0
@@ -332910,6 +344628,11 @@ Set to \fBFalse\fP to ensure that this interface is disabled.
Manage the Windows System PATH
.INDENT 0.0
.TP
+.B salt.states.win_path.__virtual__()
+Load this state if the win_path module exists
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.win_path.absent(name)
Remove the directory from the SYSTEM path
.sp
@@ -332966,6 +344689,11 @@ Windows
.sp
New in version 2016.11.0.
+.INDENT 0.0
+.TP
+.B salt.states.win_pki.__virtual__()
+Load only on minions that have the win_pki module.
+.UNINDENT
.INDENT 0.0
.TP
.B salt.states.win_pki.import_cert(name, cert_format=\(aqcer\(aq, context=\(aqLocalMachine\(aq, store=\(aqMy\(aq, exportable=True, password=\(aq\(aq, saltenv=\(aqbase\(aq)
@@ -333084,6 +344812,7 @@ New in version 2015.8.0.
.sp
.nf
.ft C
+# Set timeout to 30 minutes on battery power
monitor:
powercfg.set_timeout:
\- value: 30
@@ -333094,8 +344823,75 @@ monitor:
.UNINDENT
.INDENT 0.0
.TP
+.B salt.states.win_powercfg.__virtual__()
+Only work on Windows
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.win_powercfg.set_timeout(name, value, power=\(aqac\(aq, scheme=None)
-Set the sleep timeouts of specific items such as disk, monitor.
+Set the sleep timeouts of specific items such as disk, monitor, etc.
+.INDENT 7.0
+.TP
+.B Parameters
+.INDENT 7.0
+.IP \(bu 2
+\fBname\fP (\fI\%str\fP) \-\-
+.sp
+The setting to change, can be one of the following:
+.INDENT 2.0
+.INDENT 3.5
+.INDENT 0.0
+.IP \(bu 2
+\fBmonitor\fP
+.IP \(bu 2
+\fBdisk\fP
+.IP \(bu 2
+\fBstandby\fP
+.IP \(bu 2
+\fBhibernate\fP
+.UNINDENT
+.UNINDENT
+.UNINDENT
+
+.IP \(bu 2
+\fBvalue\fP (\fI\%int\fP) \-\- The amount of time in minutes before the item will timeout
+.IP \(bu 2
+\fBpower\fP (\fI\%str\fP) \-\-
+.sp
+Set the value for AC or DC power. Default is \fBac\fP\&. Valid options
+are:
+.INDENT 2.0
+.INDENT 3.5
+.INDENT 0.0
+.IP \(bu 2
+\fBac\fP (AC Power)
+.IP \(bu 2
+\fBdc\fP (Battery)
+.UNINDENT
+.UNINDENT
+.UNINDENT
+
+.IP \(bu 2
+\fBscheme\fP (\fI\%str\fP) \-\-
+.sp
+The scheme to use, leave as \fBNone\fP to use the current. Default is
+\fBNone\fP\&. This can be the GUID or the Alias for the Scheme. Known
+Aliases are:
+.INDENT 2.0
+.INDENT 3.5
+.INDENT 0.0
+.IP \(bu 2
+\fBSCHEME_BALANCED\fP \- Balanced
+.IP \(bu 2
+\fBSCHEME_MAX\fP \- Power saver
+.IP \(bu 2
+\fBSCHEME_MIN\fP \- High performance
+.UNINDENT
+.UNINDENT
+.UNINDENT
+
+.UNINDENT
+.UNINDENT
.sp
CLI Example:
.INDENT 7.0
@@ -333103,39 +344899,32 @@ CLI Example:
.sp
.nf
.ft C
+# Set monitor timeout to 30 minutes on Battery
monitor:
- powercfg.set_timeout:
- \- value: 30
- \- power: dc
+ powercfg.set_timeout:
+ \- value: 30
+ \- power: dc
+# Set disk timeout to 10 minutes on AC Power
disk:
- powercfg.set_timeout:
- \- value: 12
- \- power: ac
+ powercfg.set_timeout:
+ \- value: 10
+ \- power: ac
.ft P
.fi
.UNINDENT
.UNINDENT
-.INDENT 7.0
-.TP
-.B name
-The setting to change, can be one of the following: monitor, disk, standby, hibernate
-.TP
-.B timeout
-The amount of time in minutes before the item will timeout i.e\ the monitor
-.TP
-.B power
-Should we set the value for AC or DC (battery)? Valid options ac,dc.
-.TP
-.B scheme
-The scheme to use, leave as None to use the current.
-.UNINDENT
.UNINDENT
.SS salt.states.win_servermanager
.sp
Manage Windows features via the ServerManager powershell module
.INDENT 0.0
.TP
+.B salt.states.win_servermanager.__virtual__()
+Load only if win_servermanager is loaded
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.win_servermanager.installed(name, recurse=False, force=False, restart=False, source=None, exclude=None)
Install the windows feature
.INDENT 7.0
@@ -333249,6 +345038,11 @@ ISWebserverRole:
Module for managing IIS SMTP server configuration on Windows servers.
.INDENT 0.0
.TP
+.B salt.states.win_smtp_server.__virtual__()
+Load only on minions that have the win_smtp_server module.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.win_smtp_server.active_log_format(name, log_format, server=\(aqSmtpSvc/1\(aq)
Manage the active log format for the SMTP server.
.INDENT 7.0
@@ -333494,6 +345288,11 @@ smtp\-settings:
Module for managing SNMP service settings on Windows servers.
.INDENT 0.0
.TP
+.B salt.states.win_snmp.__virtual__()
+Load only on minions that have the win_snmp module.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.win_snmp.agent_settings(name, contact, location, services=None)
Manage the SNMP sysContact, sysLocation, and sysServices settings.
.INDENT 7.0
@@ -333601,6 +345400,11 @@ This is Erik\(aqs computer, don\(aqt touch!:
.UNINDENT
.INDENT 0.0
.TP
+.B salt.states.win_system.__virtual__()
+This only supports Windows
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.win_system.computer_desc(name)
Manage the computer\(aqs description field
.INDENT 7.0
@@ -333875,6 +345679,11 @@ updates:
.UNINDENT
.INDENT 0.0
.TP
+.B salt.states.win_update.__virtual__()
+Only works on Windows systems
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.win_update.downloaded(name, categories=None, skips=None, retries=10)
Cache updates for later install.
.INDENT 7.0
@@ -334046,6 +345855,11 @@ remove_updates:
.UNINDENT
.INDENT 0.0
.TP
+.B salt.states.win_wua.__virtual__()
+Only valid on Windows machines
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.win_wua.installed(name, updates=None)
Ensure Microsoft Updates are installed. Updates will be downloaded if
needed.
@@ -334301,10 +346115,10 @@ salt\-minion:
\- source: salt://signing_policies.conf
/etc/pki:
- file.directory: []
+ file.directory
/etc/pki/issued_certs:
- file.directory: []
+ file.directory
/etc/pki/ca.crt:
x509.certificate_managed:
@@ -334379,7 +346193,7 @@ handle properly formatting the text before writing the output.
.nf
.ft C
/usr/local/share/ca\-certificates:
- file.directory: []
+ file.directory
/usr/local/share/ca\-certificates/intca.crt:
x509.pem_managed:
@@ -334415,33 +346229,34 @@ This state creates a private key then requests a certificate signed by ca accord
.UNINDENT
.INDENT 0.0
.TP
+.B salt.states.x509.__virtual__()
+only load this module if the corresponding execution module is loaded
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.x509.certificate_managed(name, days_remaining=90, managed_private_key=None, append_certs=None, **kwargs)
Manage a Certificate
.INDENT 7.0
.TP
-.B name:
+.B name
Path to the certificate
.TP
-.B days_remaining:
-The minimum number of days remaining when the certificate should be recreated. Default is 90. A
-value of 0 disables automatic renewal.
+.B days_remaining
+90
+The minimum number of days remaining when the certificate should be
+recreated. A value of 0 disables automatic renewal.
.TP
-.B managed_private_key:
-Manages the private key corresponding to the certificate. All of the arguments supported by
-.nf
-:state:\(gax509.private_key_managed \(ga
-.fi
- are supported. If \fIname\fP is not speicified or is the same as the name of the certificate, the private key and certificate will be written together in the same file.
+.B managed_private_key
+Manages the private key corresponding to the certificate. All of the
+arguments supported by \fI\%x509.private_key_managed\fP are supported. If \fIname\fP is not
+speicified or is the same as the name of the certificate, the private
+key and certificate will be written together in the same file.
.TP
.B append_certs:
A list of certificates to be appended to the managed file.
.TP
.B kwargs:
-Any arguments supported by \fBx509.create_certificate\fP or
-.nf
-:state:\(gafile.managed \(ga
-.fi
- are supported.
+Any arguments supported by \fBx509.create_certificate\fP or \fBfile.managed\fP are supported.
.UNINDENT
.sp
Examples:
@@ -334493,45 +346308,45 @@ Examples:
Manage a Certificate Revocation List
.INDENT 7.0
.TP
-.B name:
+.B name
Path to the certificate
.TP
-.B signing_private_key:
+.B signing_private_key
The private key that will be used to sign this crl. This is
usually your CA\(aqs private key.
.TP
-.B signing_private_key_passphrase:
+.B signing_private_key_passphrase
Passphrase to decrypt the private key.
.TP
-.B signing_cert:
+.B signing_cert
The certificate of the authority that will be used to sign this crl.
This is usually your CA\(aqs certificate.
.TP
-.B revoked:
+.B revoked
A list of certificates to revoke. Must include either a serial number or a
the certificate itself. Can optionally include the revocation date and
notAfter date from the certificate. See example below for details.
.TP
-.B days_valid:
-The number of days the certificate should be valid for. Default is 100.
+.B days_valid
+100
+The number of days the certificate should be valid for.
.TP
-.B digest:
-The digest to use for signing the CRL.
-This has no effect on versions of pyOpenSSL less than 0.14
+.B digest
+The digest to use for signing the CRL. This has no effect on versions
+of pyOpenSSL less than 0.14.
.TP
-.B days_remaining:
-The crl should be automatically recreated if there are less than \fBdays_remaining\fP
-days until the crl expires. Set to 0 to disable automatic renewal. Default is 30.
+.B days_remaining
+30
+The crl should be automatically recreated if there are less than
+\fBdays_remaining\fP days until the crl expires. Set to 0 to disable
+automatic renewal.
.TP
-.B include_expired:
-Include expired certificates in the CRL. Default is \fBFalse\fP\&.
+.B include_expired
+False
+If \fBTrue\fP, include expired certificates in the CRL.
.TP
-.B kwargs:
-Any arguments supported by
-.nf
-:state:\(gafile.managed \(ga
-.fi
- are supported.
+.B kwargs
+Any arguments supported by \fBfile.managed\fP are supported.
.UNINDENT
.sp
Example:
@@ -334573,11 +346388,7 @@ The properties to be added to the certificate request, including items like subj
and public key. See above for valid properties.
.TP
.B kwargs:
-Any arguments supported by
-.nf
-:state:\(gafile.managed \(ga
-.fi
- are supported.
+Any arguments supported by \fBfile.managed\fP are supported.
.UNINDENT
.sp
Example:
@@ -334612,11 +346423,7 @@ The path to the file to manage
The PEM formatted text to write.
.TP
.B kwargs:
-Any arguments supported by
-.nf
-:state:\(gafile.managed \(ga
-.fi
- are supported.
+Any arguments supported by \fBfile.managed\fP are supported.
.UNINDENT
.UNINDENT
.INDENT 0.0
@@ -334701,6 +346508,11 @@ server\-warning\-message:
.UNINDENT
.INDENT 0.0
.TP
+.B salt.states.xmpp.__virtual__()
+Only load if the XMPP module is available in __salt__
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.xmpp.send_msg(name, recipient, profile)
Send a message to an XMPP user
.INDENT 7.0
@@ -334760,6 +346572,11 @@ Jiri Kotlin <\fI\%jiri.kotlin@ultimum.io\fP>
.UNINDENT
.INDENT 0.0
.TP
+.B salt.states.zabbix_host.__virtual__()
+Only make these states available if Zabbix module is available.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.zabbix_host.absent(name, **kwargs)
Ensures that the host does not exists, eventually deletes host.
.sp
@@ -334902,6 +346719,11 @@ Jiri Kotlin <\fI\%jiri.kotlin@ultimum.io\fP>
.UNINDENT
.INDENT 0.0
.TP
+.B salt.states.zabbix_hostgroup.__virtual__()
+Only make these states available if Zabbix module is available.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.zabbix_hostgroup.absent(name, **kwargs)
Ensures that the host group does not exist, eventually delete host group.
.sp
@@ -334978,6 +346800,11 @@ Raymond Kuiper <\fI\%qix@the\-wired.net\fP>
.UNINDENT
.INDENT 0.0
.TP
+.B salt.states.zabbix_mediatype.__virtual__()
+Only make these states available if Zabbix module is available.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.zabbix_mediatype.absent(name, **kwargs)
Ensures that the mediatype does not exist, eventually deletes the mediatype.
.INDENT 7.0
@@ -335055,6 +346882,11 @@ Jiri Kotlin <\fI\%jiri.kotlin@ultimum.io\fP>
.UNINDENT
.INDENT 0.0
.TP
+.B salt.states.zabbix_user.__virtual__()
+Only make these states available if Zabbix module is available.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.zabbix_user.absent(name, **kwargs)
Ensures that the user does not exist, eventually delete user.
.sp
@@ -335162,6 +346994,11 @@ Jiri Kotlin <\fI\%jiri.kotlin@ultimum.io\fP>
.UNINDENT
.INDENT 0.0
.TP
+.B salt.states.zabbix_usergroup.__virtual__()
+Only make these states available if Zabbix module is available.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.zabbix_usergroup.absent(name, **kwargs)
Ensures that the user group does not exist, eventually delete user group.
.sp
@@ -335279,6 +347116,11 @@ installed2
.UNINDENT
.INDENT 0.0
.TP
+.B salt.states.zcbuildout.__virtual__()
+Only load if zc.buildout libs available
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.zcbuildout.installed(name, config=\(aqbuildout.cfg\(aq, quiet=False, parts=None, user=None, env=(), buildout_ver=None, test_release=False, distribute=None, new_st=None, offline=False, newest=False, python=\(aq/usr/bin/python\(aq, debug=False, verbose=False, unless=None, onlyif=None, use_vt=False, loglevel=\(aqdebug\(aq, **kwargs)
Install buildout in a specific directory
.sp
@@ -335379,6 +347221,11 @@ enable_monitoring:
.UNINDENT
.INDENT 0.0
.TP
+.B salt.states.zenoss.__virtual__()
+Only load if the Zenoss execution module is available.
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.zenoss.monitored(name, device_class=None, collector=\(aqlocalhost\(aq, prod_state=None)
Ensure a device is monitored. The \(aqname\(aq given will be used for Zenoss device name and should be resolvable.
.INDENT 7.0
@@ -335516,6 +347363,11 @@ test/shares/moka@tsukune:
.UNINDENT
.INDENT 0.0
.TP
+.B salt.states.zfs.__virtual__()
+Provides zfs state
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.zfs.bookmark_absent(name, force=False, recursive=False)
ensure bookmark is absent on the system
.INDENT 7.0
@@ -335989,6 +347841,11 @@ omipkg1_no_cpu:
.UNINDENT
.INDENT 0.0
.TP
+.B salt.states.zone.__virtual__()
+Provides zone state on Solaris
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.zone.absent(name, uninstall=False)
Ensure a zone is absent
.INDENT 7.0
@@ -336312,11 +348169,7 @@ unique resource identifier
string
value for resource selection
.TP
-.B
-.nf
-**
-.fi
-kwargs
+.B kwargs
string|int|...
resource properties
.UNINDENT
@@ -336324,16 +348177,17 @@ resource properties
\fBWARNING:\fP
.INDENT 7.0
.INDENT 3.5
-Both resource_selector_property and resource_selector_value must be provided, some properties
-like \fB\(ganame\(ga\fP are already reserved by salt in there states.
+Both resource_selector_property and resource_selector_value must be
+provided, some properties like \fBname\fP are already reserved by salt in
+states.
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 7.0
.INDENT 3.5
-You can set both resource_selector_property and resource_selector_value to None for
-resources that do not require them.
+You can set both resource_selector_property and resource_selector_value
+to None for resources that do not require them.
.UNINDENT
.UNINDENT
.UNINDENT
@@ -336434,6 +348288,11 @@ Filesystem properties are also not updated, this should be managed by the zfs st
.UNINDENT
.INDENT 0.0
.TP
+.B salt.states.zpool.__virtual__()
+Provides zpool state
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.states.zpool.absent(name, export=False, force=False)
ensure storage pool is absent on the system
.INDENT 7.0
@@ -336645,6 +348504,11 @@ statistics PyPi module
.UNINDENT
.INDENT 0.0
.TP
+.B salt.thorium.calc.__virtual__()
+The statistics module must be pip installed
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.thorium.calc.add(name, num, minimum=0, maximum=0, ref=None)
Adds together the \fBnum\fP most recent values. Requires a list.
.sp
@@ -337246,11 +349110,7 @@ Add the specified values to the named list
.sp
If \fBstamp\fP is True, then the timestamp from the event will also be added
if \fBprune\fP is set to an integer higher than \fB0\fP, then only the last
-.INDENT 7.0
-.INDENT 3.5
\fBprune\fP values will be kept in the list.
-.UNINDENT
-.UNINDENT
.sp
USAGE:
.INDENT 7.0
@@ -337530,6 +349390,11 @@ base:
.UNINDENT
.INDENT 0.0
.TP
+.B salt.tops.ext_nodes.__virtual__()
+Only run if properly configured
+.UNINDENT
+.INDENT 0.0
+.TP
.B salt.tops.ext_nodes.top(**kwargs)
Run the command configured
.UNINDENT
@@ -337913,7 +349778,7 @@ sample above and use the \fBWheelClient\fP functions to show how they can
be called from a Python interpreter.
.sp
The wheel key functions can also be called via a \fBsalt\fP command at the CLI
-using the saltutil execution module\&.
+using the \fBsaltutil execution module\fP\&.
.INDENT 0.0
.TP
.B salt.wheel.key.accept(match, include_rejected=False, include_denied=False)
@@ -337974,7 +349839,7 @@ to the \fBminions\fP (accepted) directory:
.sp
.nf
.ft C
->>> wheel.cmd(\(aqaccept_dict\(aq,
+>>> wheel.cmd(\(aqkey.accept_dict\(aq,
{
\(aqminions_pre\(aq: [
\(aqjerry\(aq,
@@ -338085,18 +349950,12 @@ The hash algorithm used to calculate the fingerprint
.INDENT 0.0
.TP
.B salt.wheel.key.gen(id_=None, keysize=2048)
-.INDENT 7.0
-.INDENT 3.5
Generate a key pair. No keys are stored on the master. A key pair is
returned as a dict containing pub and priv keys. Returns a dictionary
containing the the \fBpub\fP and \fBpriv\fP keys with their generated values.
-.INDENT 0.0
+.INDENT 7.0
.TP
-.B
-.nf
-id_
-.fi
-
+.B id_
Set a name to generate a key pair for use with salt. If not specified,
a random name will be specified.
.TP
@@ -338105,57 +349964,34 @@ The size of the key pair to generate. The size must be \fB2048\fP, which
is the default, or greater. If set to a value less than \fB2048\fP, the
key size will be rounded up to \fB2048\fP\&.
.UNINDENT
-.INDENT 0.0
+.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
>>> wheel.cmd(\(aqkey.gen\(aq)
-{\(aqpub\(aq: \(aq\-\-\-\-\-BEGIN PUBLIC KEY\-\-\-\-\-
+{\(aqpub\(aq: \(aq\-\-\-\-\-BEGIN PUBLIC KEY\-\-\-\-\-\enMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBC
+\&...
+BBPfamX9gGPQTpN9e8HwcZjXQnmg8OrcUl10WHw09SDWLOlnW+ueTWugEQpPt\eniQIDAQAB\en
+\-\-\-\-\-END PUBLIC KEY\-\-\-\-\-\(aq,
+\(aqpriv\(aq: \(aq\-\-\-\-\-BEGIN RSA PRIVATE KEY\-\-\-\-\-\enMIIEpAIBAAKCAQEA42Kf+w9XeZWgguzv
+\&...
+QH3/W74X1+WTBlx4R2KGLYBiH+bCCFEQ/Zvcu4Xp4bIOPtRKozEQ==\en
+\-\-\-\-\-END RSA PRIVATE KEY\-\-\-\-\-\(aq}
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
-.UNINDENT
-.INDENT 7.0
-.TP
-.B MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBC
-\&...
-BBPfamX9gGPQTpN9e8HwcZjXQnmg8OrcUl10WHw09SDWLOlnW+ueTWugEQpPt
-.UNINDENT
-.sp
-iQIDAQAB
-.INDENT 7.0
-.INDENT 3.5
-\-\-\-\-\-END PUBLIC KEY\-\-\-\-\-\(aq,
-\(aqpriv\(aq: \(aq\-\-\-\-\-BEGIN RSA PRIVATE KEY\-\-\-\-\-
-.UNINDENT
-.UNINDENT
-.INDENT 7.0
-.TP
-.B MIIEpAIBAAKCAQEA42Kf+w9XeZWgguzv
-\&...
-QH3/W74X1+WTBlx4R2KGLYBiH+bCCFEQ/Zvcu4Xp4bIOPtRKozEQ==
-.sp
-\-\-\-\-\-END RSA PRIVATE KEY\-\-\-\-\-\(aq}
-.UNINDENT
-.UNINDENT
.INDENT 0.0
.TP
.B salt.wheel.key.gen_accept(id_, keysize=2048, force=False)
-.INDENT 7.0
-.INDENT 3.5
Generate a key pair then accept the public key. This function returns the
key pair in a dict, only the public key is preserved on the master. Returns
a dictionary.
-.INDENT 0.0
+.INDENT 7.0
.TP
-.B
-.nf
-id_
-.fi
-
+.B id_
The name of the minion for which to generate a key pair.
.TP
.B keysize
@@ -338170,44 +350006,24 @@ and not create a new key. This is the default behavior. If \fBforce\fP
is set to \fBTrue\fP, then the minion\(aqs previously accepted key will be
overwritten.
.UNINDENT
-.INDENT 0.0
+.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
>>> wheel.cmd(\(aqkey.gen_accept\(aq, [\(aqfoo\(aq])
-{\(aqpub\(aq: \(aq\-\-\-\-\-BEGIN PUBLIC KEY\-\-\-\-\-
+{\(aqpub\(aq: \(aq\-\-\-\-\-BEGIN PUBLIC KEY\-\-\-\-\-\enMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBC
+\&...
+BBPfamX9gGPQTpN9e8HwcZjXQnmg8OrcUl10WHw09SDWLOlnW+ueTWugEQpPt\eniQIDAQAB\en
+\-\-\-\-\-END PUBLIC KEY\-\-\-\-\-\(aq,
+\(aqpriv\(aq: \(aq\-\-\-\-\-BEGIN RSA PRIVATE KEY\-\-\-\-\-\enMIIEpAIBAAKCAQEA42Kf+w9XeZWgguzv
+\&...
+QH3/W74X1+WTBlx4R2KGLYBiH+bCCFEQ/Zvcu4Xp4bIOPtRKozEQ==\en
+\-\-\-\-\-END RSA PRIVATE KEY\-\-\-\-\-\(aq}
.ft P
.fi
.UNINDENT
.UNINDENT
-.UNINDENT
-.UNINDENT
-.INDENT 7.0
-.TP
-.B MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBC
-\&...
-BBPfamX9gGPQTpN9e8HwcZjXQnmg8OrcUl10WHw09SDWLOlnW+ueTWugEQpPt
-.UNINDENT
-.sp
-iQIDAQAB
-.INDENT 7.0
-.INDENT 3.5
-\-\-\-\-\-END PUBLIC KEY\-\-\-\-\-\(aq,
-\(aqpriv\(aq: \(aq\-\-\-\-\-BEGIN RSA PRIVATE KEY\-\-\-\-\-
-.UNINDENT
-.UNINDENT
-.INDENT 7.0
-.TP
-.B MIIEpAIBAAKCAQEA42Kf+w9XeZWgguzv
-.INDENT 7.0
-.INDENT 3.5
-\&...
-QH3/W74X1+WTBlx4R2KGLYBiH+bCCFEQ/Zvcu4Xp4bIOPtRKozEQ==
-.sp
-\-\-\-\-\-END RSA PRIVATE KEY\-\-\-\-\-\(aq}
-.UNINDENT
-.UNINDENT
.sp
We can now see that the \fBfoo\fP minion\(aqs key has been accepted by the master:
.INDENT 7.0
@@ -338222,7 +350038,6 @@ We can now see that the \fBfoo\fP minion\(aqs key has been accepted by the maste
.UNINDENT
.UNINDENT
.UNINDENT
-.UNINDENT
.INDENT 0.0
.TP
.B salt.wheel.key.gen_keys(keydir=None, keyname=None, keysize=None, user=None)
@@ -338236,37 +350051,26 @@ Generate master public\-key\-signature
.INDENT 0.0
.TP
.B salt.wheel.key.print(match)
-.INDENT 7.0
-.INDENT 3.5
Return information about the key. Returns a dictionary.
-.INDENT 0.0
+.INDENT 7.0
.TP
.B match
The key to return information about.
.UNINDENT
-.INDENT 0.0
+.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
>>> wheel.cmd(\(aqkey.key_str\(aq, [\(aqminion1\(aq])
-{\(aqminions\(aq: {\(aqminion1\(aq: \(aq\-\-\-\-\-BEGIN PUBLIC KEY\-\-\-\-\-
+{\(aqminions\(aq: {\(aqminion1\(aq: \(aq\-\-\-\-\-BEGIN PUBLIC KEY\-\-\-\-\-\enMIIBIjANBgkqhkiG9w0B
+\&...
+TWugEQpPt\eniQIDAQAB\en\-\-\-\-\-END PUBLIC KEY\-\-\-\-\-\(aq}}
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
-.UNINDENT
-.INDENT 7.0
-.TP
-.B MIIBIjANBgkqhkiG9w0B
-\&...
-TWugEQpPt
-.UNINDENT
-.sp
-iQIDAQAB
-\-\-\-\-\-END PUBLIC KEY\-\-\-\-\-\(aq}}
-.UNINDENT
.INDENT 0.0
.TP
.B salt.wheel.key.list(match)
@@ -339651,716 +351455,6 @@ Returns the result from the wheel module
.UNINDENT
.UNINDENT
.UNINDENT
-.SS HTTP Modules
-.sp
-This tutorial demonstrates using the various HTTP modules available in Salt.
-These modules wrap the Python \fBtornado\fP, \fBurllib2\fP, and \fBrequests\fP
-libraries, extending them in a manner that is more consistent with Salt
-workflows.
-.SS The \fBsalt.utils.http\fP Library
-.sp
-This library forms the core of the HTTP modules. Since it is designed to be used
-from the minion as an execution module, in addition to the master as a runner,
-it was abstracted into this multi\-use library. This library can also be imported
-by 3rd\-party programs wishing to take advantage of its extended functionality.
-.sp
-Core functionality of the execution, state, and runner modules is derived from
-this library, so common usages between them are described here. Documentation
-specific to each module is described below.
-.sp
-This library can be imported with:
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-import salt.utils.http
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.SS Configuring Libraries
-.sp
-This library can make use of either \fBtornado\fP, which is required by Salt,
-\fBurllib2\fP, which ships with Python, or \fBrequests\fP, which can be installed
-separately. By default, \fBtornado\fP will be used. In order to switch to
-\fBurllib2\fP, set the following variable:
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-backend: urllib2
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-In order to switch to \fBrequests\fP, set the following variable:
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-backend: requests
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-This can be set in the master or minion configuration file, or passed as an
-option directly to any \fBhttp.query()\fP functions.
-.SS \fBsalt.utils.http.query()\fP
-.sp
-This function forms a basic query, but with some add\-ons not present in the
-\fBtornado\fP, \fBurllib2\fP, and \fBrequests\fP libraries. Not all functionality
-currently available in these libraries has been added, but can be in future
-iterations.
-.SS HTTPS Request Methods
-.sp
-A basic query can be performed by calling this function with no more than a
-single URL:
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-salt.utils.http.query(\(aqhttp://example.com\(aq)
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-By default the query will be performed with a \fBGET\fP method. The method can
-be overridden with the \fBmethod\fP argument:
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-salt.utils.http.query(\(aqhttp://example.com/delete/url\(aq, \(aqDELETE\(aq)
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-When using the \fBPOST\fP method (and others, such as \fBPUT\fP), extra data is usually
-sent as well. This data can be sent directly, in whatever format is
-required by the remote server (XML, JSON, plain text, etc).
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-salt.utils.http.query(
- \(aqhttp://example.com/delete/url\(aq,
- method=\(aqPOST\(aq,
- data=json.loads(mydict)
-)
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.SS Data Formatting and Templating
-.sp
-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):
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-salt.utils.http.query(
- \(aqhttp://example.com/post/url\(aq,
- method=\(aqPOST\(aq,
- data_file=\(aq/srv/salt/somefile.xml\(aq
-)
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-To pass through a file that contains jinja + yaml templating (the default):
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-salt.utils.http.query(
- \(aqhttp://example.com/post/url\(aq,
- method=\(aqPOST\(aq,
- data_file=\(aq/srv/salt/somefile.jinja\(aq,
- data_render=True,
- template_dict={\(aqkey1\(aq: \(aqvalue1\(aq, \(aqkey2\(aq: \(aqvalue2\(aq}
-)
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-To pass through a file that contains mako templating:
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-salt.utils.http.query(
- \(aqhttp://example.com/post/url\(aq,
- method=\(aqPOST\(aq,
- data_file=\(aq/srv/salt/somefile.mako\(aq,
- data_render=True,
- data_renderer=\(aqmako\(aq,
- template_dict={\(aqkey1\(aq: \(aqvalue1\(aq, \(aqkey2\(aq: \(aqvalue2\(aq}
-)
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-Because this function uses Salt\(aqs own rendering system, any Salt renderer can
-be used. Because Salt\(aqs renderer requires \fB__opts__\fP to be set, an \fBopts\fP
-dictionary should be passed in. If it is not, then the default \fB__opts__\fP
-values for the node type (master or minion) will be used. Because this library
-is intended primarily for use by minions, the default node type is \fBminion\fP\&.
-However, this can be changed to \fBmaster\fP if necessary.
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-salt.utils.http.query(
- \(aqhttp://example.com/post/url\(aq,
- method=\(aqPOST\(aq,
- data_file=\(aq/srv/salt/somefile.jinja\(aq,
- data_render=True,
- template_dict={\(aqkey1\(aq: \(aqvalue1\(aq, \(aqkey2\(aq: \(aqvalue2\(aq},
- opts=__opts__
-)
-
-salt.utils.http.query(
- \(aqhttp://example.com/post/url\(aq,
- method=\(aqPOST\(aq,
- data_file=\(aq/srv/salt/somefile.jinja\(aq,
- data_render=True,
- template_dict={\(aqkey1\(aq: \(aqvalue1\(aq, \(aqkey2\(aq: \(aqvalue2\(aq},
- node=\(aqmaster\(aq
-)
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.SS Headers
-.sp
-Headers may also be passed through, either as a \fBheader_list\fP, a
-\fBheader_dict\fP, or as a \fBheader_file\fP\&. As with the \fBdata_file\fP, the
-\fBheader_file\fP may also be templated. Take note that because HTTP headers are
-normally syntactically\-correct YAML, they will automatically be imported as an
-a Python dict.
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-salt.utils.http.query(
- \(aqhttp://example.com/delete/url\(aq,
- method=\(aqPOST\(aq,
- header_file=\(aq/srv/salt/headers.jinja\(aq,
- header_render=True,
- header_renderer=\(aqjinja\(aq,
- template_dict={\(aqkey1\(aq: \(aqvalue1\(aq, \(aqkey2\(aq: \(aqvalue2\(aq}
-)
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-Because much of the data that would be templated between headers and data may be
-the same, the \fBtemplate_dict\fP is the same for both. Correcting possible
-variable name collisions is up to the user.
-.SS Authentication
-.sp
-The \fBquery()\fP function supports basic HTTP authentication. A username and
-password may be passed in as \fBusername\fP and \fBpassword\fP, respectively.
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-salt.utils.http.query(
- \(aqhttp://example.com\(aq,
- username=\(aqlarry\(aq,
- password=\(ga5700g3543v4r\(ga,
-)
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.SS Cookies and Sessions
-.sp
-Cookies are also supported, using Python\(aqs built\-in \fBcookielib\fP\&. However, they
-are turned off by default. To turn cookies on, set \fBcookies\fP to True.
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-salt.utils.http.query(
- \(aqhttp://example.com\(aq,
- cookies=True
-)
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-By default cookies are stored in Salt\(aqs cache directory, normally
-\fB/var/cache/salt\fP, as a file called \fBcookies.txt\fP\&. However, this location
-may be changed with the \fBcookie_jar\fP argument:
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-salt.utils.http.query(
- \(aqhttp://example.com\(aq,
- cookies=True,
- cookie_jar=\(aq/path/to/cookie_jar.txt\(aq
-)
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-By default, the format of the cookie jar is LWP (aka, lib\-www\-perl). This
-default was chosen because it is a human\-readable text file. If desired, the
-format of the cookie jar can be set to Mozilla:
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-salt.utils.http.query(
- \(aqhttp://example.com\(aq,
- cookies=True,
- cookie_jar=\(aq/path/to/cookie_jar.txt\(aq,
- cookie_format=\(aqmozilla\(aq
-)
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-Because Salt commands are normally one\-off commands that are piped together,
-this library cannot normally behave as a normal browser, with session cookies
-that persist across multiple HTTP requests. However, the session can be
-persisted in a separate cookie jar. The default filename for this file, inside
-Salt\(aqs cache directory, is \fBcookies.session.p\fP\&. This can also be changed.
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-salt.utils.http.query(
- \(aqhttp://example.com\(aq,
- persist_session=True,
- session_cookie_jar=\(aq/path/to/jar.p\(aq
-)
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-The format of this file is msgpack, which is consistent with much of the rest
-of Salt\(aqs internal structure. Historically, the extension for this file is
-\fB\&.p\fP\&. There are no current plans to make this configurable.
-.SS Proxy
-.sp
-If the \fBtornado\fP backend is used (\fBtornado\fP is the default), proxy
-information configured in \fBproxy_host\fP, \fBproxy_port\fP, \fBproxy_username\fP,
-and \fBproxy_password\fP from the \fB__opts__\fP dictionary will be used. Normally
-these are set in the minion configuration file.
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-proxy_host: proxy.my\-domain
-proxy_port: 31337
-proxy_username: charon
-proxy_password: obolus
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-salt.utils.http.query(
- \(aqhttp://example.com\(aq,
- opts=__opts__,
- backend=\(aqtornado\(aq
-)
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.SS Return Data
-.sp
-\fBNOTE:\fP
-.INDENT 0.0
-.INDENT 3.5
-Return data encoding
-.sp
-If \fBdecode\fP is set to \fBTrue\fP, \fBquery()\fP will attempt to decode the
-return data. \fBdecode_type\fP defaults to \fBauto\fP\&. Set it to a specific
-encoding, \fBxml\fP, for example, to override autodetection.
-.UNINDENT
-.UNINDENT
-.sp
-Because Salt\(aqs http library was designed to be used with REST interfaces,
-\fBquery()\fP will attempt to decode the data received from the remote server
-when \fBdecode\fP is set to \fBTrue\fP\&. First it will check the \fBContent\-type\fP
-header to try and find references to XML. If it does not find any, it will look
-for references to JSON. If it does not find any, it will fall back to plain
-text, which will not be decoded.
-.sp
-JSON data is translated into a dict using Python\(aqs built\-in \fBjson\fP library.
-XML is translated using \fBsalt.utils.xml_util\fP, which will use Python\(aqs
-built\-in XML libraries to attempt to convert the XML into a dict. In order to
-force either JSON or XML decoding, the \fBdecode_type\fP may be set:
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-salt.utils.http.query(
- \(aqhttp://example.com\(aq,
- decode_type=\(aqxml\(aq
-)
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-Once translated, the return dict from \fBquery()\fP will include a dict called
-\fBdict\fP\&.
-.sp
-If the data is not to be translated using one of these methods, decoding may be
-turned off.
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-salt.utils.http.query(
- \(aqhttp://example.com\(aq,
- decode=False
-)
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-If decoding is turned on, and references to JSON or XML cannot be found, then
-this module will default to plain text, and return the undecoded data as
-\fBtext\fP (even if text is set to \fBFalse\fP; see below).
-.sp
-The \fBquery()\fP function can return the HTTP status code, headers, and/or text
-as required. However, each must individually be turned on.
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-salt.utils.http.query(
- \(aqhttp://example.com\(aq,
- status=True,
- headers=True,
- text=True
-)
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-The return from these will be found in the return dict as \fBstatus\fP,
-\fBheaders\fP and \fBtext\fP, respectively.
-.SS Writing Return Data to Files
-.sp
-It is possible to write either the return data or headers to files, as soon as
-the response is received from the server, but specifying file locations via the
-\fBtext_out\fP or \fBheaders_out\fP arguments. \fBtext\fP and \fBheaders\fP do not need
-to be returned to the user in order to do this.
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-salt.utils.http.query(
- \(aqhttp://example.com\(aq,
- text=False,
- headers=False,
- text_out=\(aq/path/to/url_download.txt\(aq,
- headers_out=\(aq/path/to/headers_download.txt\(aq,
-)
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.SS SSL Verification
-.sp
-By default, this function will verify SSL certificates. However, for testing or
-debugging purposes, SSL verification can be turned off.
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-salt.utils.http.query(
- \(aqhttps://example.com\(aq,
- verify_ssl=False,
-)
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.SS CA Bundles
-.sp
-The \fBrequests\fP library has its own method of detecting which CA (certificate
-authority) bundle file to use. Usually this is implemented by the packager for
-the specific operating system distribution that you are using. However,
-\fBurllib2\fP requires a little more work under the hood. By default, Salt will
-try to auto\-detect the location of this file. However, if it is not in an
-expected location, or a different path needs to be specified, it may be done so
-using the \fBca_bundle\fP variable.
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-salt.utils.http.query(
- \(aqhttps://example.com\(aq,
- ca_bundle=\(aq/path/to/ca_bundle.pem\(aq,
-)
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.SS Updating CA Bundles
-.sp
-The \fBupdate_ca_bundle()\fP function can be used to update the bundle file at a
-specified location. If the target location is not specified, then it will
-attempt to auto\-detect the location of the bundle file. If the URL to download
-the bundle from does not exist, a bundle will be downloaded from the cURL
-website.
-.sp
-CAUTION: The \fBtarget\fP and the \fBsource\fP should always be specified! Failure
-to specify the \fBtarget\fP may result in the file being written to the wrong
-location on the local system. Failure to specify the \fBsource\fP may cause the
-upstream URL to receive excess unnecessary traffic, and may cause a file to be
-download which is hazardous or does not meet the needs of the user.
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-salt.utils.http.update_ca_bundle(
- target=\(aq/path/to/ca\-bundle.crt\(aq,
- source=\(aqhttps://example.com/path/to/ca\-bundle.crt\(aq,
- opts=__opts__,
-)
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-The \fBopts\fP parameter should also always be specified. If it is, then the
-\fBtarget\fP and the \fBsource\fP may be specified in the relevant configuration
-file (master or minion) as \fBca_bundle\fP and \fBca_bundle_url\fP, respectively.
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-ca_bundle: /path/to/ca\-bundle.crt
-ca_bundle_url: https://example.com/path/to/ca\-bundle.crt
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-If Salt is unable to auto\-detect the location of the CA bundle, it will raise
-an error.
-.sp
-The \fBupdate_ca_bundle()\fP function can also be passed a string or a list of
-strings which represent files on the local system, which should be appended (in
-the specified order) to the end of the CA bundle file. This is useful in
-environments where private certs need to be made available, and are not
-otherwise reasonable to add to the bundle file.
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-salt.utils.http.update_ca_bundle(
- opts=__opts__,
- merge_files=[
- \(aq/etc/ssl/private_cert_1.pem\(aq,
- \(aq/etc/ssl/private_cert_2.pem\(aq,
- \(aq/etc/ssl/private_cert_3.pem\(aq,
- ]
-)
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.SS Test Mode
-.sp
-This function may be run in test mode. This mode will perform all work up until
-the actual HTTP request. By default, instead of performing the request, an empty
-dict will be returned. Using this function with \fBTRACE\fP logging turned on will
-reveal the contents of the headers and POST data to be sent.
-.sp
-Rather than returning an empty dict, an alternate \fBtest_url\fP may be passed in.
-If this is detected, then test mode will replace the \fBurl\fP with the
-\fBtest_url\fP, set \fBtest\fP to \fBTrue\fP in the return data, and perform the rest
-of the requested operations as usual. This allows a custom, non\-destructive URL
-to be used for testing when necessary.
-.SS Execution Module
-.sp
-The \fBhttp\fP execution module is a very thin wrapper around the
-\fBsalt.utils.http\fP library. The \fBopts\fP can be passed through as well, but if
-they are not specified, the minion defaults will be used as necessary.
-.sp
-Because passing complete data structures from the command line can be tricky at
-best and dangerous (in terms of execution injection attacks) at worse, the
-\fBdata_file\fP, and \fBheader_file\fP are likely to see more use here.
-.sp
-All methods for the library are available in the execution module, as kwargs.
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-salt myminion http.query http://example.com/restapi method=POST \e
- username=\(aqlarry\(aq password=\(aq5700g3543v4r\(aq headers=True text=True \e
- status=True decode_type=xml data_render=True \e
- header_file=/tmp/headers.txt data_file=/tmp/data.txt \e
- header_render=True cookies=True persist_session=True
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.SS Runner Module
-.sp
-Like the execution module, the \fBhttp\fP runner module is a very thin wrapper
-around the \fBsalt.utils.http\fP library. The only significant difference is that
-because runners execute on the master instead of a minion, a target is not
-required, and default opts will be derived from the master config, rather than
-the minion config.
-.sp
-All methods for the library are available in the runner module, as kwargs.
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-salt\-run http.query http://example.com/restapi method=POST \e
- username=\(aqlarry\(aq password=\(aq5700g3543v4r\(aq headers=True text=True \e
- status=True decode_type=xml data_render=True \e
- header_file=/tmp/headers.txt data_file=/tmp/data.txt \e
- header_render=True cookies=True persist_session=True
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.SS State Module
-.sp
-The state module is a wrapper around the runner module, which applies stateful
-logic to a query. All kwargs as listed above are specified as usual in state
-files, but two more kwargs are available to apply stateful logic. A required
-parameter is \fBmatch\fP, which specifies a pattern to look for in the return
-text. By default, this will perform a string comparison of looking for the
-value of match in the return text. In Python terms this looks like:
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-if match in html_text:
- return True
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-If more complex pattern matching is required, a regular expression can be used
-by specifying a \fBmatch_type\fP\&. By default this is set to \fBstring\fP, but it
-can be manually set to \fBpcre\fP instead. Please note that despite the name, this
-will use Python\(aqs \fBre.search()\fP rather than \fBre.match()\fP\&.
-.sp
-Therefore, the following states are valid:
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-http://example.com/restapi:
- http.query:
- \- match: \(aqSUCCESS\(aq
- \- username: \(aqlarry\(aq
- \- password: \(aq5700g3543v4r\(aq
- \- data_render: True
- \- header_file: /tmp/headers.txt
- \- data_file: /tmp/data.txt
- \- header_render: True
- \- cookies: True
- \- persist_session: True
-
-http://example.com/restapi:
- http.query:
- \- match_type: pcre
- \- match: \(aq(?i)succe[ss|ed]\(aq
- \- username: \(aqlarry\(aq
- \- password: \(aq5700g3543v4r\(aq
- \- data_render: True
- \- header_file: /tmp/headers.txt
- \- data_file: /tmp/data.txt
- \- header_render: True
- \- cookies: True
- \- persist_session: True
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-In addition to, or instead of a match pattern, the status code for a URL can be
-checked. This is done using the \fBstatus\fP argument:
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-http://example.com/:
- http.query:
- \- status: \(aq200\(aq
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-If both are specified, both will be checked, but if only one is \fBTrue\fP and the
-other is \fBFalse\fP, then \fBFalse\fP will be returned. In this case, the comments
-in the return data will contain information for troubleshooting.
-.sp
-Because this is a monitoring state, it will return extra data to code that
-expects it. This data will always include \fBtext\fP and \fBstatus\fP\&. Optionally,
-\fBheaders\fP and \fBdict\fP may also be requested by setting the \fBheaders\fP and
-\fBdecode\fP arguments to True, respectively.
.SS Writing netapi modules
.sp
\fBnetapi\fP modules, put simply, bind a port and start a service.
@@ -340771,1098 +351865,6 @@ Using a pluggable minion cache modules allows for the data stored on a Salt Mast
Salt Minions to be replicated on other Salt Masters the Minion is connected to. Please see
the Minion Data Cache documentation for more information and configuration
examples.
-.SS Using Salt at scale
-.sp
-The focus of this tutorial will be building a Salt infrastructure for handling
-large numbers of minions. This will include tuning, topology, and best practices.
-.sp
-For how to install the Salt Master please
-go here: \fI\%Installing saltstack\fP
-.sp
-\fBNOTE:\fP
-.INDENT 0.0
-.INDENT 3.5
-This tutorial is intended for large installations, although these same settings
-won\(aqt hurt, it may not be worth the complexity to smaller installations.
-.sp
-When used with minions, the term \(aqmany\(aq refers to at least a thousand
-and \(aqa few\(aq always means 500.
-.sp
-For simplicity reasons, this tutorial will default to the standard ports
-used by Salt.
-.UNINDENT
-.UNINDENT
-.SS The Master
-.sp
-The most common problems on the Salt Master are:
-.INDENT 0.0
-.IP 1. 3
-too many minions authing at once
-.IP 2. 3
-too many minions re\-authing at once
-.IP 3. 3
-too many minions re\-connecting at once
-.IP 4. 3
-too many minions returning at once
-.IP 5. 3
-too few resources (CPU/HDD)
-.UNINDENT
-.sp
-The first three are all "thundering herd" problems. To mitigate these issues
-we must configure the minions to back\-off appropriately when the Master is
-under heavy load.
-.sp
-The fourth is caused by masters with little hardware resources in combination
-with a possible bug in ZeroMQ. At least that\(aqs what it looks like till today
-(\fI\%Issue 118651\fP,
-\fI\%Issue 5948\fP,
-\fI\%Mail thread\fP)
-.sp
-To fully understand each problem, it is important to understand, how Salt works.
-.sp
-Very briefly, the Salt Master offers two services to the minions.
-.INDENT 0.0
-.IP \(bu 2
-a job publisher on port 4505
-.IP \(bu 2
-an open port 4506 to receive the minions returns
-.UNINDENT
-.sp
-All minions are always connected to the publisher on port 4505 and only connect
-to the open return port 4506 if necessary. On an idle Master, there will only
-be connections on port 4505.
-.SS Too many minions authing
-.sp
-When the Minion service is first started up, it will connect to its Master\(aqs publisher
-on port 4505. If too many minions are started at once, this can cause a "thundering herd".
-This can be avoided by not starting too many minions at once.
-.sp
-The connection itself usually isn\(aqt the culprit, the more likely cause of master\-side
-issues is the authentication that the Minion must do with the Master. If the Master
-is too heavily loaded to handle the auth request it will time it out. The Minion
-will then wait \fIacceptance_wait_time\fP to retry. If \fIacceptance_wait_time_max\fP is
-set then the Minion will increase its wait time by the \fIacceptance_wait_time\fP each
-subsequent retry until reaching \fIacceptance_wait_time_max\fP\&.
-.SS Too many minions re\-authing
-.sp
-This is most likely to happen in the testing phase of a Salt deployment, when
-all Minion keys have already been accepted, but the framework is being tested
-and parameters are frequently changed in the Salt Master\(aqs configuration
-file(s).
-.sp
-The Salt Master generates a new AES key to encrypt its publications at certain
-events such as a Master restart or the removal of a Minion key. If you are
-encountering this problem of too many minions re\-authing against the Master,
-you will need to recalibrate your setup to reduce the rate of events like a
-Master restart or Minion key removal (\fBsalt\-key \-d\fP).
-.sp
-When the Master generates a new AES key, the minions aren\(aqt notified of this
-but will discover it on the next pub job they receive. When the Minion
-receives such a job it will then re\-auth with the Master. Since Salt does
-minion\-side filtering this means that all the minions will re\-auth on the next
-command published on the master\-\- causing another "thundering herd". This can
-be avoided by setting the
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-random_reauth_delay: 60
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-in the minions configuration file to a higher value and stagger the amount
-of re\-auth attempts. Increasing this value will of course increase the time
-it takes until all minions are reachable via Salt commands.
-.SS Too many minions re\-connecting
-.sp
-By default the zmq socket will re\-connect every 100ms which for some larger
-installations may be too quick. This will control how quickly the TCP session is
-re\-established, but has no bearing on the auth load.
-.sp
-To tune the minions sockets reconnect attempts, there are a few values in
-the sample configuration file (default values)
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-recon_default: 1000
-recon_max: 5000
-recon_randomize: True
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.INDENT 0.0
-.IP \(bu 2
-recon_default: the default value the socket should use, i.e. 1000. This value is in
-milliseconds. (1000ms = 1 second)
-.IP \(bu 2
-recon_max: the max value that the socket should use as a delay before trying to reconnect
-This value is in milliseconds. (5000ms = 5 seconds)
-.IP \(bu 2
-recon_randomize: enables randomization between recon_default and recon_max
-.UNINDENT
-.sp
-To tune this values to an existing environment, a few decision have to be made.
-.INDENT 0.0
-.IP 1. 3
-How long can one wait, before the minions should be online and reachable via Salt?
-.IP 2. 3
-How many reconnects can the Master handle without a syn flood?
-.UNINDENT
-.sp
-These questions can not be answered generally. Their answers depend on the
-hardware and the administrators requirements.
-.sp
-Here is an example scenario with the goal, to have all minions reconnect
-within a 60 second time\-frame on a Salt Master service restart.
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-recon_default: 1000
-recon_max: 59000
-recon_randomize: True
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-Each Minion will have a randomized reconnect value between \(aqrecon_default\(aq
-and \(aqrecon_default + recon_max\(aq, which in this example means between 1000ms
-and 60000ms (or between 1 and 60 seconds). The generated random\-value will
-be doubled after each attempt to reconnect (ZeroMQ default behavior).
-.sp
-Lets say the generated random value is 11 seconds (or 11000ms).
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-reconnect 1: wait 11 seconds
-reconnect 2: wait 22 seconds
-reconnect 3: wait 33 seconds
-reconnect 4: wait 44 seconds
-reconnect 5: wait 55 seconds
-reconnect 6: wait time is bigger than 60 seconds (recon_default + recon_max)
-reconnect 7: wait 11 seconds
-reconnect 8: wait 22 seconds
-reconnect 9: wait 33 seconds
-reconnect x: etc.
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-With a thousand minions this will mean
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-1000/60 = ~16
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-round about 16 connection attempts a second. These values should be altered to
-values that match your environment. Keep in mind though, that it may grow over
-time and that more minions might raise the problem again.
-.SS Too many minions returning at once
-.sp
-This can also happen during the testing phase, if all minions are addressed at
-once with
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-$ salt * disk.usage
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-it may cause thousands of minions trying to return their data to the Salt Master
-open port 4506. Also causing a flood of syn\-flood if the Master can\(aqt handle that many
-returns at once.
-.sp
-This can be easily avoided with Salt\(aqs batch mode:
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-$ salt * disk.usage \-b 50
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-This will only address 50 minions at once while looping through all addressed
-minions.
-.SS Too few resources
-.sp
-The masters resources always have to match the environment. There is no way
-to give good advise without knowing the environment the Master is supposed to
-run in. But here are some general tuning tips for different situations:
-.SS The Master is CPU bound
-.sp
-Salt uses RSA\-Key\-Pairs on the masters and minions end. Both generate 4096
-bit key\-pairs on first start. While the key\-size for the Master is currently
-not configurable, the minions keysize can be configured with different
-key\-sizes. For example with a 2048 bit key:
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-keysize: 2048
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-With thousands of decryptions, the amount of time that can be saved on the
-masters end should not be neglected. See here for reference:
-\fI\%Pull Request 9235\fP how much
-influence the key\-size can have.
-.sp
-Downsizing the Salt Master\(aqs key is not that important, because the minions
-do not encrypt as many messages as the Master does.
-.sp
-In installations with large or with complex pillar files, it is possible
-for the master to exhibit poor performance as a result of having to render
-many pillar files at once. This exhibit itself in a number of ways, both
-as high load on the master and on minions which block on waiting for their
-pillar to be delivered to them.
-.sp
-To reduce pillar rendering times, it is possible to cache pillars on the
-master. To do this, see the set of master configuration options which
-are prefixed with \fIpillar_cache\fP\&.
-.sp
-\fBNOTE:\fP
-.INDENT 0.0
-.INDENT 3.5
-Caching pillars on the master may introduce security considerations.
-Be certain to read caveats outlined in the master configuration file
-to understand how pillar caching may affect a master\(aqs ability to
-protect sensitive data!
-.UNINDENT
-.UNINDENT
-.SS The Master is disk IO bound
-.sp
-By default, the Master saves every Minion\(aqs return for every job in its
-job\-cache. The cache can then be used later, to lookup results for previous
-jobs. The default directory for this is:
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-cachedir: /var/cache/salt
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-and then in the \fB/proc\fP directory.
-.sp
-Each job return for every Minion is saved in a single file. Over time this
-directory can grow quite large, depending on the number of published jobs. The
-amount of files and directories will scale with the number of jobs published and
-the retention time defined by
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-keep_jobs: 24
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-250 jobs/day * 2000 minions returns = 500,000 files a day
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-If no job history is needed, the job cache can be disabled:
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-job_cache: False
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-If the job cache is necessary there are (currently) 2 options:
-.INDENT 0.0
-.IP \(bu 2
-ext_job_cache: this will have the minions store their return data directly
-into a returner (not sent through the Master)
-.IP \(bu 2
-master_job_cache (New in \fI2014.7.0\fP): this will make the Master store the job
-data using a returner (instead of the local job cache on disk).
-.UNINDENT
-.sp
-If a master has many accepted keys, it may take a long time to publish a job
-because the master much first determine the matching minions and deliver
-that information back to the waiting client before the job can be published.
-.sp
-To mitigate this, a key cache may be enabled. This will reduce the load
-on the master to a single file open instead of thousands or tens of thousands.
-.sp
-This cache is updated by the maintanence process, however, which means that
-minions with keys that are accepted may not be targeted by the master
-for up to sixty seconds by default.
-.sp
-To enable the master key cache, set \fIkey_cache: \(aqsched\(aq\fP in the master
-configuration file.
-.SS Multi Master Tutorial
-.sp
-As of Salt 0.16.0, the ability to connect minions to multiple masters has been
-made available. The multi\-master system allows for redundancy of Salt
-masters and facilitates multiple points of communication out to minions. When
-using a multi\-master setup, all masters are running hot, and any active master
-can be used to send commands out to the minions.
-.sp
-\fBNOTE:\fP
-.INDENT 0.0
-.INDENT 3.5
-If you need failover capabilities with multiple masters, there is also a
-MultiMaster\-PKI setup available, that uses a different topology
-\fI\%MultiMaster\-PKI with Failover Tutorial\fP
-.UNINDENT
-.UNINDENT
-.sp
-In 0.16.0, the masters do not share any information, keys need to be accepted
-on both masters, and shared files need to be shared manually or use tools like
-the git fileserver backend to ensure that the \fBfile_roots\fP are
-kept consistent.
-.sp
-Beginning with Salt 2016.11.0, the Pluggable Minion Data Cache
-was introduced. The minion data cache contains the Salt Mine data, minion grains, and minion
-pillar information cached on the Salt Master. By default, Salt uses the \fBlocalfs\fP cache
-module, but other external data stores can be used instead.
-.sp
-Using a pluggable minion cache modules allows for the data stored on a Salt Master about
-Salt Minions to be replicated on other Salt Masters the Minion is connected to. Please see
-the Minion Data Cache documentation for more information and configuration
-examples.
-.SS Summary of Steps
-.INDENT 0.0
-.IP 1. 3
-Create a redundant master server
-.IP 2. 3
-Copy primary master key to redundant master
-.IP 3. 3
-Start redundant master
-.IP 4. 3
-Configure minions to connect to redundant master
-.IP 5. 3
-Restart minions
-.IP 6. 3
-Accept keys on redundant master
-.UNINDENT
-.SS Prepping a Redundant Master
-.sp
-The first task is to prepare the redundant master. If the redundant master is
-already running, stop it. There is only one requirement when preparing a
-redundant master, which is that masters share the same private key. When the
-first master was created, the master\(aqs identifying key pair was generated and
-placed in the master\(aqs \fBpki_dir\fP\&. The default location of the master\(aqs key
-pair is \fB/etc/salt/pki/master/\fP\&. Take the private key, \fBmaster.pem\fP, and
-copy it to the same location on the redundant master. Do the same for the
-master\(aqs public key, \fBmaster.pub\fP\&. Assuming that no minions have yet been
-connected to the new redundant master, it is safe to delete any existing key
-in this location and replace it.
-.sp
-\fBNOTE:\fP
-.INDENT 0.0
-.INDENT 3.5
-There is no logical limit to the number of redundant masters that can be
-used.
-.UNINDENT
-.UNINDENT
-.sp
-Once the new key is in place, the redundant master can be safely started.
-.SS Configure Minions
-.sp
-Since minions need to be master\-aware, the new master needs to be added to the
-minion configurations. Simply update the minion configurations to list all
-connected masters:
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-master:
- \- saltmaster1.example.com
- \- saltmaster2.example.com
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-Now the minion can be safely restarted.
-.sp
-\fBNOTE:\fP
-.INDENT 0.0
-.INDENT 3.5
-If the ipc_mode for the minion is set to TCP (default in Windows), then
-each minion in the multi\-minion setup (one per master) needs its own
-tcp_pub_port and tcp_pull_port.
-.sp
-If these settings are left as the default 4510/4511, each minion object
-will receive a port 2 higher than the previous. Thus the first minion will
-get 4510/4511, the second will get 4512/4513, and so on. If these port
-decisions are unacceptable, you must configure tcp_pub_port and
-tcp_pull_port with lists of ports for each master. The length of these
-lists should match the number of masters, and there should not be overlap
-in the lists.
-.UNINDENT
-.UNINDENT
-.sp
-Now the minions will check into the original master and also check into the new
-redundant master. Both masters are first\-class and have rights to the minions.
-.sp
-\fBNOTE:\fP
-.INDENT 0.0
-.INDENT 3.5
-Minions can automatically detect failed masters and attempt to reconnect
-to reconnect to them quickly. To enable this functionality, set
-\fImaster_alive_interval\fP in the minion config and specify a number of
-seconds to poll the masters for connection status.
-.sp
-If this option is not set, minions will still reconnect to failed masters
-but the first command sent after a master comes back up may be lost while
-the minion authenticates.
-.UNINDENT
-.UNINDENT
-.SS Sharing Files Between Masters
-.sp
-Salt does not automatically share files between multiple masters. A number of
-files should be shared or sharing of these files should be strongly considered.
-.SS Minion Keys
-.sp
-Minion keys can be accepted the normal way using \fBsalt\-key\fP on both
-masters. Keys accepted, deleted, or rejected on one master will NOT be
-automatically managed on redundant masters; this needs to be taken care of by
-running salt\-key on both masters or sharing the
-\fB/etc/salt/pki/master/{minions,minions_pre,minions_rejected}\fP directories
-between masters.
-.sp
-\fBNOTE:\fP
-.INDENT 0.0
-.INDENT 3.5
-While sharing the \fB/etc/salt/pki/master\fP directory will work, it is
-strongly discouraged, since allowing access to the \fBmaster.pem\fP key
-outside of Salt creates a \fISERIOUS\fP security risk.
-.UNINDENT
-.UNINDENT
-.SS File_Roots
-.sp
-The \fBfile_roots\fP contents should be kept consistent between
-masters. Otherwise state runs will not always be consistent on minions since
-instructions managed by one master will not agree with other masters.
-.sp
-The recommended way to sync these is to use a fileserver backend like gitfs or
-to keep these files on shared storage.
-.sp
-\fBIMPORTANT:\fP
-.INDENT 0.0
-.INDENT 3.5
-If using gitfs/git_pillar with the cachedir shared between masters using
-\fI\%GlusterFS\fP, nfs, or another network filesystem, and the masters are
-running Salt 2015.5.9 or later, it is strongly recommended not to turn off
-\fBgitfs_global_lock\fP/\fBgit_pillar_global_lock\fP as
-doing so will cause lock files to be removed if they were created by a
-different master.
-.UNINDENT
-.UNINDENT
-.SS Pillar_Roots
-.sp
-Pillar roots should be given the same considerations as
-\fBfile_roots\fP\&.
-.SS Master Configurations
-.sp
-While reasons may exist to maintain separate master configurations, it is wise
-to remember that each master maintains independent control over minions.
-Therefore, access controls should be in sync between masters unless a valid
-reason otherwise exists to keep them inconsistent.
-.sp
-These access control options include but are not limited to:
-.INDENT 0.0
-.IP \(bu 2
-external_auth
-.IP \(bu 2
-publisher_acl
-.IP \(bu 2
-peer
-.IP \(bu 2
-peer_run
-.UNINDENT
-.SS Multi\-Master\-PKI Tutorial With Failover
-.sp
-This tutorial will explain, how to run a salt\-environment where a single
-minion can have multiple masters and fail\-over between them if its current
-master fails.
-.sp
-The individual steps are
-.INDENT 0.0
-.IP \(bu 2
-setup the master(s) to sign its auth\-replies
-.IP \(bu 2
-setup minion(s) to verify master\-public\-keys
-.IP \(bu 2
-enable multiple masters on minion(s)
-.IP \(bu 2
-enable master\-check on minion(s)
-.INDENT 2.0
-.INDENT 3.5
-Please note, that it is advised to have good knowledge of the salt\-
-authentication and communication\-process to understand this tutorial.
-All of the settings described here, go on top of the default
-authentication/communication process.
-.UNINDENT
-.UNINDENT
-.UNINDENT
-.SS Motivation
-.sp
-The default behaviour of a salt\-minion is to connect to a master and accept
-the masters public key. With each publication, the master sends his public\-key
-for the minion to check and if this public\-key ever changes, the minion
-complains and exits. Practically this means, that there can only be a single
-master at any given time.
-.sp
-Would it not be much nicer, if the minion could have any number of masters
-(1:n) and jump to the next master if its current master died because of a
-network or hardware failure?
-.sp
-\fBNOTE:\fP
-.INDENT 0.0
-.INDENT 3.5
-There is also a MultiMaster\-Tutorial with a different approach and topology
-than this one, that might also suite your needs or might even be better suited
-\fI\%Multi\-Master Tutorial\fP
-.UNINDENT
-.UNINDENT
-.sp
-It is also desirable, to add some sort of authenticity\-check to the very first
-public key a minion receives from a master. Currently a minions takes the
-first masters public key for granted.
-.SS The Goal
-.sp
-Setup the master to sign the public key it sends to the minions and enable the
-minions to verify this signature for authenticity.
-.SS Prepping the master to sign its public key
-.sp
-For signing to work, both master and minion must have the signing and/or
-verification settings enabled. If the master signs the public key but the
-minion does not verify it, the minion will complain and exit. The same
-happens, when the master does not sign but the minion tries to verify.
-.sp
-The easiest way to have the master sign its public key is to set
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-master_sign_pubkey: True
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-After restarting the salt\-master service, the master will automatically
-generate a new key\-pair
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-master_sign.pem
-master_sign.pub
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-A custom name can be set for the signing key\-pair by setting
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-master_sign_key_name:
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-The master will then generate that key\-pair upon restart and use it for
-creating the public keys signature attached to the auth\-reply.
-.sp
-The computation is done for every auth\-request of a minion. If many minions
-auth very often, it is advised to use conf_master:\fImaster_pubkey_signature\fP
-and conf_master:\fImaster_use_pubkey_signature\fP settings described below.
-.sp
-If multiple masters are in use and should sign their auth\-replies, the signing
-key\-pair master_sign.* has to be copied to each master. Otherwise a minion
-will fail to verify the masters public when connecting to a different master
-than it did initially. That is because the public keys signature was created
-with a different signing key\-pair.
-.SS Prepping the minion to verify received public keys
-.sp
-The minion must have the public key (and only that one!) available to be
-able to verify a signature it receives. That public key (defaults to
-master_sign.pub) must be copied from the master to the minions pki\-directory.
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-/etc/salt/pki/minion/master_sign.pub
-
-DO NOT COPY THE master_sign.pem FILE. IT MUST STAY ON THE MASTER AND
-ONLY THERE!
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-When that is done, enable the signature checking in the minions configuration
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-verify_master_pubkey_sign: True
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-and restart the minion. For the first try, the minion should be run in manual
-debug mode.
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-salt\-minion \-l debug
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-Upon connecting to the master, the following lines should appear on the output:
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-[DEBUG ] Attempting to authenticate with the Salt Master at 172.16.0.10
-[DEBUG ] Loaded minion key: /etc/salt/pki/minion/minion.pem
-[DEBUG ] salt.crypt.verify_signature: Loading public key
-[DEBUG ] salt.crypt.verify_signature: Verifying signature
-[DEBUG ] Successfully verified signature of master public key with verification public key master_sign.pub
-[INFO ] Received signed and verified master pubkey from master 172.16.0.10
-[DEBUG ] Decrypting the current master AES key
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-If the signature verification fails, something went wrong and it will look
-like this
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-[DEBUG ] Attempting to authenticate with the Salt Master at 172.16.0.10
-[DEBUG ] Loaded minion key: /etc/salt/pki/minion/minion.pem
-[DEBUG ] salt.crypt.verify_signature: Loading public key
-[DEBUG ] salt.crypt.verify_signature: Verifying signature
-[DEBUG ] Failed to verify signature of public key
-[CRITICAL] The Salt Master server\(aqs public key did not authenticate!
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-In a case like this, it should be checked, that the verification pubkey
-(master_sign.pub) on the minion is the same as the one on the master.
-.sp
-Once the verification is successful, the minion can be started in daemon mode
-again.
-.sp
-For the paranoid among us, its also possible to verify the publication whenever
-it is received from the master. That is, for every single auth\-attempt which
-can be quite frequent. For example just the start of the minion will force the
-signature to be checked 6 times for various things like auth, mine,
-highstate, etc.
-.sp
-If that is desired, enable the setting
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-always_verify_signature: True
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.SS Multiple Masters For A Minion
-.sp
-Configuring multiple masters on a minion is done by specifying two settings:
-.INDENT 0.0
-.IP \(bu 2
-a list of masters addresses
-.IP \(bu 2
-what type of master is defined
-.UNINDENT
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-master:
- \- 172.16.0.10
- \- 172.16.0.11
- \- 172.16.0.12
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-master_type: failover
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-This tells the minion that all the master above are available for it to
-connect to. When started with this configuration, it will try the master
-in the order they are defined. To randomize that order, set
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-master_shuffle: True
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-The master\-list will then be shuffled before the first connection attempt.
-.sp
-The first master that accepts the minion, is used by the minion. If the
-master does not yet know the minion, that counts as accepted and the minion
-stays on that master.
-.sp
-For the minion to be able to detect if its still connected to its current
-master enable the check for it
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-master_alive_interval:
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-If the loss of the connection is detected, the minion will temporarily
-remove the failed master from the list and try one of the other masters
-defined (again shuffled if that is enabled).
-.SS Testing the setup
-.sp
-At least two running masters are needed to test the failover setup.
-.sp
-Both masters should be running and the minion should be running on the command
-line in debug mode
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-salt\-minion \-l debug
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-The minion will connect to the first master from its master list
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-[DEBUG ] Attempting to authenticate with the Salt Master at 172.16.0.10
-[DEBUG ] Loaded minion key: /etc/salt/pki/minion/minion.pem
-[DEBUG ] salt.crypt.verify_signature: Loading public key
-[DEBUG ] salt.crypt.verify_signature: Verifying signature
-[DEBUG ] Successfully verified signature of master public key with verification public key master_sign.pub
-[INFO ] Received signed and verified master pubkey from master 172.16.0.10
-[DEBUG ] Decrypting the current master AES key
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-A test.ping on the master the minion is currently connected to should be run to
-test connectivity.
-.sp
-If successful, that master should be turned off. A firewall\-rule denying the
-minions packets will also do the trick.
-.sp
-Depending on the configured conf_minion:\fImaster_alive_interval\fP, the minion
-will notice the loss of the connection and log it to its logfile.
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-[INFO ] Connection to master 172.16.0.10 lost
-[INFO ] Trying to tune in to next master from master\-list
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-The minion will then remove the current master from the list and try connecting
-to the next master
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-[INFO ] Removing possibly failed master 172.16.0.10 from list of masters
-[WARNING ] Master ip address changed from 172.16.0.10 to 172.16.0.11
-[DEBUG ] Attempting to authenticate with the Salt Master at 172.16.0.11
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-If everything is configured correctly, the new masters public key will be
-verified successfully
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-[DEBUG ] Loaded minion key: /etc/salt/pki/minion/minion.pem
-[DEBUG ] salt.crypt.verify_signature: Loading public key
-[DEBUG ] salt.crypt.verify_signature: Verifying signature
-[DEBUG ] Successfully verified signature of master public key with verification public key master_sign.pub
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-the authentication with the new master is successful
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-[INFO ] Received signed and verified master pubkey from master 172.16.0.11
-[DEBUG ] Decrypting the current master AES key
-[DEBUG ] Loaded minion key: /etc/salt/pki/minion/minion.pem
-[INFO ] Authentication with master successful!
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-and the minion can be pinged again from its new master.
-.SS Performance Tuning
-.sp
-With the setup described above, the master computes a signature for every
-auth\-request of a minion. With many minions and many auth\-requests, that
-can chew up quite a bit of CPU\-Power.
-.sp
-To avoid that, the master can use a pre\-created signature of its public\-key.
-The signature is saved as a base64 encoded string which the master reads
-once when starting and attaches only that string to auth\-replies.
-.sp
-Enabling this also gives paranoid users the possibility, to have the signing
-key\-pair on a different system than the actual salt\-master and create the public
-keys signature there. Probably on a system with more restrictive firewall rules,
-without internet access, less users, etc.
-.sp
-That signature can be created with
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-salt\-key \-\-gen\-signature
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-This will create a default signature file in the master pki\-directory
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-/etc/salt/pki/master/master_pubkey_signature
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-It is a simple text\-file with the binary\-signature converted to base64.
-.sp
-If no signing\-pair is present yet, this will auto\-create the signing pair and
-the signature file in one call
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-salt\-key \-\-gen\-signature \-\-auto\-create
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-Telling the master to use the pre\-created signature is done with
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-master_use_pubkey_signature: True
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-That requires the file \(aqmaster_pubkey_signature\(aq to be present in the masters
-pki\-directory with the correct signature.
-.sp
-If the signature file is named differently, its name can be set with
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-master_pubkey_signature:
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-With many masters and many public\-keys (default and signing), it is advised to
-use the salt\-masters hostname for the signature\-files name. Signatures can be
-easily confused because they do not provide any information about the key the
-signature was created from.
-.sp
-Verifying that everything works is done the same way as above.
-.SS How the signing and verification works
-.sp
-The default key\-pair of the salt\-master is
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-/etc/salt/pki/master/master.pem
-/etc/salt/pki/master/master.pub
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-To be able to create a signature of a message (in this case a public\-key),
-another key\-pair has to be added to the setup. Its default name is:
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-master_sign.pem
-master_sign.pub
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-The combination of the master.* and master_sign.* key\-pairs give the
-possibility of generating signatures. The signature of a given message
-is unique and can be verified, if the public\-key of the signing\-key\-pair
-is available to the recipient (the minion).
-.sp
-The signature of the masters public\-key in master.pub is computed with
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-master_sign.pem
-master.pub
-M2Crypto.EVP.sign_update()
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-This results in a binary signature which is converted to base64 and attached
-to the auth\-reply send to the minion.
-.sp
-With the signing\-pairs public\-key available to the minion, the attached
-signature can be verified with
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-master_sign.pub
-master.pub
-M2Cryptos EVP.verify_update().
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
-.sp
-When running multiple masters, either the signing key\-pair has to be present
-on all of them, or the master_pubkey_signature has to be pre\-computed for
-each master individually (because they all have different public\-keys).
-.INDENT 0.0
-.INDENT 3.5
-DO NOT PUT THE SAME master.pub ON ALL MASTERS FOR EASE OF USE.
-.UNINDENT
-.UNINDENT
.SH MINION DATA CACHE
.sp
New in version 2016.11.0.
@@ -343089,7 +353091,7 @@ To avoid such issues, always pretend Windows is case\-sensitive and use the righ
case for names, e.g. specify \fBuser=Administrator\fP instead of
\fBuser=administrator\fP\&.
.sp
-Follow \fI\%issue 11801\fP for any changes to this behavior.
+Follow \fI\%issue #11801\fP for any changes to this behavior.
.SS Dealing with various username forms
.sp
Salt does not understand the various forms that Windows usernames can come in,
@@ -343100,7 +353102,7 @@ the username without the domain or host information.
Using these alternative forms will likely confuse Salt and cause odd errors to
happen. Use only the raw username value in the correct case to avoid problems.
.sp
-Follow \fI\%issue 11801\fP for any changes to this behavior.
+Follow \fI\%issue #11801\fP for any changes to this behavior.
.SS Specifying the None group
.sp
Each Windows system has built\-in _None_ group. This is the default \(aqprimary
@@ -343393,11 +353395,24 @@ SaltStack has its own coding style guide that informs contributors on various co
approaches. Please review the Salt Coding Style documentation
for information about Salt\(aqs particular coding patterns.
.sp
-Within the Salt Coding Style documentation, there is a section
-about running Salt\(aqs \fB\&.pylintrc\fP file. SaltStack recommends running the \fB\&.pylintrc\fP
-file on any files you are changing with your code contribution before submitting a
-pull request to Salt\(aqs repository. Please see the Linting
-documentation for more information.
+Within the Salt Coding Style documentation, there is a
+section about running Salt\(aqs \fB\&.testing.pylintrc\fP file. SaltStack recommends
+running the \fB\&.testing.pylintrc\fP file on any files you are changing with your
+code contribution before submitting a pull request to Salt\(aqs repository. Please
+see the Linting documentation for more information.
+.sp
+\fBNOTE:\fP
+.INDENT 0.0
+.INDENT 3.5
+There are two pylint files in the \fBsalt\fP directory. One is the
+\fB\&.pylintrc\fP file and the other is the \fB\&.testing.pylintrc\fP file. The
+tests that run in Jenkins against GitHub Pull Requests use
+\fB\&.testing.pylintrc\fP\&. The \fBtesting.pylintrc\fP file is a little less
+strict than the \fB\&.pylintrc\fP and is used to make it easier for contributors
+to submit changes. The \fB\&.pylintrc\fP file can be used for linting, but the
+\fBtesting.pylintrc\fP is the source of truth when submitting pull requests.
+.UNINDENT
+.UNINDENT
.SS Sending a GitHub pull request
.sp
Sending pull requests on GitHub is the preferred method for receiving
@@ -344974,118 +354989,123 @@ SaltStack uses several labeling schemes to help facilitate code contributions
and bug resolution. See the Labels and Milestones documentation for more information.
.SS GitHub Labels and Milestones
.sp
-SaltStack uses several label categories, as well as milestones, to triage incoming issues and pull requests in the
-GitHub issue tracker. Labels are used to sort issues by type, priority, severity, status, functional area, functional
-group, and targeted release and pull requests by status, functional area, functional group, type of change, and test
-status. Milestones are used to indicate whether an issue is fully triaged or is scheduled to be fixed by SaltStack in
-an upcoming sprint.
+SaltStack uses several label categories, as well as milestones, to triage
+incoming issues and pull requests in the GitHub issue tracker. Labels are used
+to sort issues by type, priority, severity, status, functional area, functional
+group, and targeted release and pull requests by status, functional area,
+functional group, type of change, and test status. Milestones are used to
+indicate whether an issue is fully triaged or is scheduled to be fixed by
+SaltStack in an upcoming sprint.
.SS Milestones
.sp
-All issues are assigned to a milestone, whereas pull requests are almost never assigned to a milestone as the mean
-lifetime of pull requests is short enough that there is no need to track them temporally.
+All issues are assigned to a milestone, whereas pull requests are almost never
+assigned to a milestone as the mean lifetime of pull requests is short enough
+that there is no need to track them temporally.
.sp
-SaltStack uses milestones to indicate which issues are blocked on submitter or upstream actions, are approved, or are
-scheduled to be fixed or implemented in an upcoming sprint. If an issue is not attached to a sprint milestone, you are
-welcome to work on it at your own desire and convenience. If it is attached to a sprint milestone and you have already
-begun working on it or have a solution in mind or have other ideas related to the issue, you are encouraged to
-coordinate with the assignee via the GitHub issue tracker to create the best possible solution or implementation.
+SaltStack uses milestones to indicate which issues are blocked on submitter or
+upstream actions, are approved, or are scheduled to be fixed or implemented in
+an upcoming sprint. If an issue is not attached to a sprint milestone, you are
+welcome to work on it at your own desire and convenience. If it is attached to
+a sprint milestone and you have already begun working on it or have a solution
+in mind or have other ideas related to the issue, you are encouraged to
+coordinate with the assignee via the GitHub issue tracker to create the best
+possible solution or implementation.
.INDENT 0.0
-.TP
-.B \fBApproved\fP
-The issue has been validated and has all necessary information.
-.TP
-.B \fBBlocked\fP
-The issue is waiting on actions by parties outside of SaltStack, such as receiving more information from the
-submitter or resolution of an upstream issue. This milestone is usually applied in conjunction with the labels
-\fBInfo Needed\fP, \fBQuestion\fP, \fBExpected Behavior\fP, \fBWon\(aqt Fix For Now\fP, or \fBUpstream Bug\fP\&.
-.TP
-.B \fBUnder Review\fP
-The issue is having further validation done by a SaltStack engineer.
-.TP
-.B \fB\fP
-The issue is being actively worked on by a SaltStack engineer. Sprint milestones names are constructed from the
-chemical symbol of the next release\(aqs codename and the number of sprints until that release is made. For example,
-if the next release codename is \fBNeon\fP and there are five sprints until that release, the corresponding sprint
-milestone will be called \fBNe 5\fP\&. See for a discussion of Salt\(aqs release
+.IP \(bu 2
+\fBApproved\fP \- The issue has been validated and has all necessary information.
+.IP \(bu 2
+\fBBlocked\fP \- The issue is waiting on actions by parties outside of
+SaltStack, such as receiving more information from the submitter or
+resolution of an upstream issue. This milestone is usually applied in
+conjunction with the labels \fBInfo Needed\fP, \fBQuestion\fP, \fBExpected
+Behavior\fP, \fBWon\(aqt Fix For Now\fP, or \fBUpstream Bug\fP\&.
+.IP \(bu 2
+\fBUnder Review\fP \- The issue is having further validation done by a SaltStack
+engineer.
+.IP \(bu 2
+\fB\fP \- The issue is being actively worked on by a SaltStack engineer.
+Sprint milestones names are constructed from the chemical symbol of the next
+release\(aqs codename and the number of sprints until that release is made. For
+example, if the next release codename is \fBNeon\fP and there are five sprints
+until that release, the corresponding sprint milestone will be called \fBNe
+5\fP\&. See here for a discussion of Salt\(aqs release
codenames.
.UNINDENT
.SS Labels
.sp
-Labels are used to sort and describe issues and pull requests. Some labels are usually reserved for one or the other,
-though most labels may be applied to both.
+Labels are used to sort and describe issues and pull requests. Some labels are
+usually reserved for one or the other, though most labels may be applied to
+both.
.sp
-New issues will receive at least one label and a milestone, and new pull requests will receive at least one label.
-Except for the \fI\%functional area\fP and \fI\%functional group\fP
-label categories, issues will generally receive only up to one label per category.
+New issues will receive at least one label and a milestone, and new pull
+requests will receive at least one label. Except for the \fI\%functional area\fP and \fI\%functional group\fP
+label categories, issues will generally receive only up to one label per
+category.
.SS Type
.sp
-Issues are categorized into one of several types. Type labels are almost never used for pull requests. GitHub treats
-pull requests like issues in many ways, so a pull request could be considered an issue with an implicit \fBPull Request\fP
-type label applied.
+Issues are categorized into one of several types. Type labels are almost never
+used for pull requests. GitHub treats pull requests like issues in many ways,
+so a pull request could be considered an issue with an implicit \fBPull
+Request\fP type label applied.
.INDENT 0.0
-.TP
-.B \fBFeature\fP
-The issue is a request for new functionality including changes, enhancements, refactors, etc.
-.TP
-.B \fBBug\fP
-The issue documents broken, incorrect, or confusing behavior. This label is always accompanied by a \fI\%severity
-label\fP\&.
-.TP
-.B \fBDuplicate\fP
-The issue is a duplicate of another feature request or bug report.
-.TP
-.B \fBUpstream Bug\fP
-The issue is a result of an upstream issue.
-.TP
-.B \fBQuestion\fP
-The issue is more of a question than a request for new features or a report of broken features, but can sometimes
-lead to further discussion or changes of confusing or incongruous behavior or documentation.
-.TP
-.B \fBExpected Behavior\fP
-The issue is a bug report of intended functionality.
+.IP \(bu 2
+\fBFeature\fP \- The issue is a request for new functionality including changes,
+enhancements, refactors, etc.
+.IP \(bu 2
+\fBBug\fP \- The issue documents broken, incorrect, or confusing behavior. This
+label is always accompanied by a \fI\%severity label\fP\&.
+.IP \(bu 2
+\fBDuplicate\fP \- The issue is a duplicate of another feature request or bug
+report.
+.IP \(bu 2
+\fBUpstream Bug\fP \- The issue is a result of an upstream issue.
+.IP \(bu 2
+\fBQuestion\fP \- The issue is more of a question than a request for new
+features or a report of broken features, but can sometimes lead to further
+discussion or changes of confusing or incongruous behavior or documentation.
+.IP \(bu 2
+\fBExpected Behavior\fP \- The issue is a bug report of intended functionality.
.UNINDENT
.SS Priority
.sp
-An issue\(aqs priority is relative to its \fI\%functional area\fP\&. If a bug report, for example,
-about \fBgitfs\fP indicates that all users of \fBgitfs\fP will encounter this bug, then a \fBP1\fP label will be applied, even
-though users who are not using \fBgitfs\fP will not encounter the bug. If a feature is requested by many users, it may be
-given a high priority.
+An issue\(aqs priority is relative to its \fI\%functional area\fP\&. If a bug report, for example, about \fBgitfs\fP
+indicates that all users of \fBgitfs\fP will encounter this bug, then a \fBP1\fP
+label will be applied, even though users who are not using \fBgitfs\fP will not
+encounter the bug. If a feature is requested by many users, it may be given a
+high priority.
.INDENT 0.0
-.TP
-.B \fBP1\fP
-The issue will be seen by all users.
-.TP
-.B \fBP2\fP
-The issue will be seen by most users.
-.TP
-.B \fBP3\fP
-The issue will be seen by about half of users.
-.TP
-.B \fBP4\fP
-The issue will not be seen by most users. Usually the issue is a very specific use case or corner case.
+.IP \(bu 2
+\fBP1\fP \- The issue will be seen by all users.
+.IP \(bu 2
+\fBP2\fP \- The issue will be seen by most users.
+.IP \(bu 2
+\fBP3\fP \- The issue will be seen by about half of users.
+.IP \(bu 2
+\fBP4\fP \- The issue will not be seen by most users. Usually the issue is a
+very specific use case or corner case.
.UNINDENT
.SS Severity
.sp
Severity labels are almost always only applied to issues labeled \fBBug\fP\&.
.INDENT 0.0
-.TP
-.B \fBBlocker\fP
-The issue is blocking an impending release.
-.TP
-.B \fBCritical\fP
-The issue causes data loss, crashes or hangs salt processes, makes the system unresponsive, etc.
-.TP
-.B \fBHigh Severity\fP
-The issue reports incorrect functionality, bad functionality, a confusing user experience, etc.
-.TP
-.B \fBMedium Severity\fP
-The issue reports cosmetic items, formatting, spelling, colors, etc.
+.IP \(bu 2
+\fBBlocker\fP \- The issue is blocking an impending release.
+.IP \(bu 2
+\fBCritical\fP \- The issue causes data loss, crashes or hangs salt processes,
+makes the system unresponsive, etc.
+.IP \(bu 2
+\fBHigh Severity\fP \- The issue reports incorrect functionality, bad
+functionality, a confusing user experience, etc.
+.IP \(bu 2
+\fBMedium Severity\fP \- The issue reports cosmetic items, formatting, spelling,
+colors, etc.
.UNINDENT
.SS Functional Area
.sp
-Many major components of Salt have corresponding GitHub labels. These labels are applied to all issues and pull
-requests as is reasonably appropriate. They are useful in organizing issues and pull requests according to the source
-code relevant to issues or the source code changed by pull requests.
+Many major components of Salt have corresponding GitHub labels. These labels
+are applied to all issues and pull requests as is reasonably appropriate. They
+are useful in organizing issues and pull requests according to the source code
+relevant to issues or the source code changed by pull requests.
.INDENT 0.0
.IP \(bu 2
\fBExecution Module\fP
@@ -345128,172 +355148,184 @@ code relevant to issues or the source code changed by pull requests.
.UNINDENT
.SS Functional Group
.sp
-These labels sort issues and pull requests according to the internal SaltStack engineering teams.
+These labels sort issues and pull requests according to the internal SaltStack
+engineering teams.
.INDENT 0.0
-.TP
-.B \fBCore\fP
-The issue or pull request relates to code that is central or existential to Salt itself.
-.TP
-.B \fBPlatform\fP
-The issue or pull request relates to support and integration with various platforms like traditional operating
-systems as well as containers, platform\-based utilities like filesystems, command schedulers, etc., and
-system\-based applications like webservers, databases, etc.
-.TP
-.B \fBRIoT\fP
-The issue or pull request relates to support and integration with various abstract systems like cloud providers,
-hypervisors, API\-based services, etc.
-.TP
-.B \fBConsole\fP
-The issue or pull request relates to the SaltStack enterprise console.
-.TP
-.B \fBDocumentation\fP
-The issue or pull request relates to documentation.
+.IP \(bu 2
+\fBCore\fP \- The issue or pull request relates to code that is central or
+existential to Salt itself.
+.IP \(bu 2
+\fBPlatform\fP \- The issue or pull request relates to support and integration
+with various platforms like traditional operating systems as well as
+containers, platform\-based utilities like filesystems, command schedulers,
+etc., and system\-based applications like webservers, databases, etc.
+.IP \(bu 2
+\fBRIoT\fP \- The issue or pull request relates to support and integration with
+various abstract systems like cloud providers, hypervisors, API\-based
+services, etc.
+.IP \(bu 2
+\fBConsole\fP \- The issue or pull request relates to the SaltStack enterprise
+console.
+.IP \(bu 2
+\fBDocumentation\fP \- The issue or pull request relates to documentation.
.UNINDENT
.SS Status
.sp
-Status labels are used to define and track the state of issues and pull requests. Not all potential statuses correspond
-to a label, but some statuses are common enough that labels have been created for them. If an issue has not been moved
-beyond the \fBBlocked\fP milestone, it is very likely that it will only have a status label.
+Status labels are used to define and track the state of issues and pull
+requests. Not all potential statuses correspond to a label, but some statuses
+are common enough that labels have been created for them. If an issue has not
+been moved beyond the \fBBlocked\fP milestone, it is very likely that it will
+only have a status label.
.INDENT 0.0
-.TP
-.B \fBBugfix \- back\-port\fP
-The pull request needs to be back\-ported to an older release branch. This is done by recreating the pull
-request against that branch. Once the back\-port is completed, this label is replaced
-with a \fBBugfix \- [Done] back\-ported\fP label. Normally, new features should go into the develop and bug fixes into
-the oldest supported release branch, see \&.
-.TP
-.B \fBBugfix \- [Done] back\-ported\fP
-The pull request has been back\-ported to an older branch.
-.TP
-.B \fBCannot Reproduce\fP
-The issue is a bug and has been reviewed by a SaltStack engineer, but it cannot be replicated with the provided
-information and context. Those involved with the bug will need to work through additional ideas until the bug can
-be isolated and verified.
-.TP
-.B \fBConfirmed\fP
-The issue is a bug and has been confirmed by a SaltStack engineer, who often documents a minimal working example
-that reproduces the bug.
-.TP
-.B \fBFixed Pending Verification\fP
-The issue is a bug and has been fixed by one or more pull requests, which should link to the issue. Closure of the
-issue is contingent upon confirmation of resolution from the submitter. If the submitter reports a negative
-confirmation, this label is removed. If no response is given after a few weeks, then the issue will be assumed
-fixed and closed.
-.TP
-.B \fBInfo Needed\fP
-The issue needs more information before it can be verified and resolved. For a feature request this may include a
-description of the use cases. Almost all bug reports need to include at least the versions of salt and its
-dependencies, the system type and version, commands used, debug logs, error messages, and relevant configs.
-.TP
-.B \fBPending Changes\fP
-The pull request needs additional changes before it can be merged.
-.TP
-.B \fBPending Discussion\fP
-The issue or pull request needs more discussion before it can be closed or merged. The status of the issue or pull
-request is not clear or apparent enough for definite action to be taken, or additional input from SaltStack, the
-submitter, or another party has been requested.
+.IP \(bu 2
+\fBBugfix \- back\-port\fP The pull request needs to be back\-ported to an older
+release branch. This is done by recreating the pull request against that branch. Once the back\-port is
+completed, this label is replaced with a \fBBugfix \- [Done] back\-ported\fP
+label. Normally, new features should go into the develop and bug fixes into
+the oldest supported release branch, see here\&.
+.IP \(bu 2
+\fBBugfix \- [Done] back\-ported\fP \- The pull request has been back\-ported to an
+older branch.
+.IP \(bu 2
+\fBCannot Reproduce\fP \- The issue is a bug and has been reviewed by a
+SaltStack engineer, but it cannot be replicated with the provided information
+and context. Those involved with the bug will need to work through
+additional ideas until the bug can be isolated and verified.
+.IP \(bu 2
+\fBConfirmed\fP \- The issue is a bug and has been confirmed by a SaltStack
+engineer, who often documents a minimal working example that reproduces the
+bug.
+.IP \(bu 2
+\fBFixed Pending Verification\fP \- The issue is a bug and has been fixed by one
+or more pull requests, which should link to the issue. Closure of the issue
+is contingent upon confirmation of resolution from the submitter. If the
+submitter reports a negative confirmation, this label is removed. If no
+response is given after a few weeks, then the issue will be assumed fixed and
+closed.
+.IP \(bu 2
+\fBInfo Needed\fP \- The issue needs more information before it can be verified
+and resolved. For a feature request this may include a description of the
+use cases. Almost all bug reports need to include at least the versions of
+salt and its dependencies, the system type and version, commands used, debug
+logs, error messages, and relevant configs.
+.IP \(bu 2
+\fBPending Changes\fP \- The pull request needs additional changes before it can
+be merged.
+.IP \(bu 2
+\fBPending Discussion\fP \- The issue or pull request needs more discussion
+before it can be closed or merged. The status of the issue or pull request
+is not clear or apparent enough for definite action to be taken, or
+additional input from SaltStack, the submitter, or another party has been
+requested.
.sp
-If the issue is not a pull request, once the discussion has arrived at a cogent conclusion, this label will be
-removed and the issue will be accepted. If it is a pull request, the results of the discussion may require
-additional changes and thus, a \fBPending Changes\fP label.
-.TP
-.B \fBWon\(aqt Fix for Now\fP
-The issue is legitimate, but it is not something the SaltStack team is currently able or willing to fix or
-implement. Issues having this label may be revisited in the future.
+If the issue is not a pull request, once the discussion has arrived at a
+cogent conclusion, this label will be removed and the issue will be accepted.
+If it is a pull request, the results of the discussion may require additional
+changes and thus, a \fBPending Changes\fP label.
+.IP \(bu 2
+\fBWon\(aqt Fix for Now\fP \- The issue is legitimate, but it is not something the
+SaltStack team is currently able or willing to fix or implement. Issues
+having this label may be revisited in the future.
.UNINDENT
.SS Type of Change
.sp
-Every pull request should receive a change label. These labels measure the quantity of change as well as the
-significance of the change. The amount of change and the importance of the code area changed are considered, but often
-the depth of secondary code review required and the potential repercussions of the change may also advise the label
-choice.
+Every pull request should receive a change label. These labels measure the
+quantity of change as well as the significance of the change. The amount of
+change and the importance of the code area changed are considered, but often
+the depth of secondary code review required and the potential repercussions of
+the change may also advise the label choice.
.sp
-Core code areas include: state compiler, crypto engine, master and minion and syndic daemons, transport, pillar
-rendering, loader, transport layer, event system, salt.utils, client, cli, logging, netapi, runner engine, templating
-engine, top file compilation, file client, file server, mine, salt\-ssh, test runner, etc.
+Core code areas include: state compiler, crypto engine, master and minion and
+syndic daemons, transport, pillar rendering, loader, transport layer, event
+system, salt.utils, client, cli, logging, netapi, runner engine, templating
+engine, top file compilation, file client, file server, mine, salt\-ssh, test
+runner, etc.
.sp
-Non\-core code usually constitutes the specific set of plugins for each of the several plugin layers of Salt: execution
-modules, states, runners, returners, clouds, etc.
+Non\-core code usually constitutes the specific set of plugins for each of the
+several plugin layers of Salt: execution modules, states, runners, returners,
+clouds, etc.
.INDENT 0.0
-.TP
-.B \fBMinor Change\fP
-.INDENT 7.0
+.IP \(bu 2
+\fBMinor Change\fP
+.INDENT 2.0
.IP \(bu 2
Less than 64 lines changed, or
.IP \(bu 2
Less than 8 core lines changed
.UNINDENT
-.TP
-.B \fBMedium Change\fP
-.INDENT 7.0
+.IP \(bu 2
+\fBMedium Change\fP
+.INDENT 2.0
.IP \(bu 2
Less than 256 lines changed, or
.IP \(bu 2
Less than 64 core lines changed
.UNINDENT
-.TP
-.B \fBMaster Change\fP
-.INDENT 7.0
+.IP \(bu 2
+\fBMaster Change\fP
+.INDENT 2.0
.IP \(bu 2
More than 256 lines changed, or
.IP \(bu 2
More than 64 core lines changed
.UNINDENT
-.TP
-.B \fBExpert Change\fP
-.INDENT 7.0
+.IP \(bu 2
+\fBExpert Change\fP
+.INDENT 2.0
.IP \(bu 2
Needs specialized, in\-depth review
.UNINDENT
.UNINDENT
.SS Test Status
.sp
-These labels relate to the status of the automated tests that run on pull requests. If the tests on a pull request fail
-and are not overridden by one of these labels, the pull request submitter needs to update the code and/or tests so that
-the tests pass and the pull request can be merged.
+These labels relate to the status of the automated tests that run on pull
+requests. If the tests on a pull request fail and are not overridden by one of
+these labels, the pull request submitter needs to update the code and/or tests
+so that the tests pass and the pull request can be merged.
.INDENT 0.0
-.TP
-.B \fBLint\fP
-The pull request has passed all tests except for the code lint checker.
-.TP
-.B \fBTests Passed\fP
-The pull request has passed all tests even though some test results are negative. Sometimes the automated testing
-infrastructure will encounter internal errors unrelated to the code change in the pull request that cause test runs
-to fail. These errors can be caused by cloud host and network issues and also Jenkins issues like erroneously
-accumulating workspace artifacts, resource exhaustion, and bugs that arise from long running Jenkins processes.
+.IP \(bu 2
+\fBLint\fP \- The pull request has passed all tests except for the code lint
+checker.
+.IP \(bu 2
+\fBTests Passed\fP \- The pull request has passed all tests even though some
+test results are negative. Sometimes the automated testing infrastructure
+will encounter internal errors unrelated to the code change in the pull
+request that cause test runs to fail. These errors can be caused by cloud
+host and network issues and also Jenkins issues like erroneously accumulating
+workspace artifacts, resource exhaustion, and bugs that arise from long
+running Jenkins processes.
.UNINDENT
.SS Other
.sp
-These labels indicate miscellaneous issue types or statuses that are common or important enough to be tracked and sorted
-with labels.
+These labels indicate miscellaneous issue types or statuses that are common or
+important enough to be tracked and sorted with labels.
.INDENT 0.0
-.TP
-.B \fBAwesome\fP
-The pull request implements an especially well crafted solution, or a very difficult but necessary change.
-.TP
-.B \fBHelp Wanted\fP
-The issue appears to have a simple solution. Issues having this label
-should be a good starting place for new contributors to Salt.
-.TP
-.B \fBNeeds Testcase\fP
-The issue or pull request relates to a feature that needs test coverage. The pull request containing the tests
-should reference the issue or pull request having this label, whereupon the label should be removed.
-.TP
-.B \fBRegression\fP
-The issue is a bug that breaks functionality known to work in previous releases.
-.TP
-.B \fBStory\fP
-The issue is used by a SaltStack engineer to track progress on multiple related issues in a single place.
-.TP
-.B \fBStretch\fP
-The issue is an optional goal for the current sprint but may not be delivered.
-.TP
-.B \fBZD\fP
-The issue is related to a Zendesk customer support ticket.
-.TP
-.B \fB\fP
-The issue is scheduled to be implemented by \fB\fP\&. See for a
-discussion of Salt\(aqs release codenames.
+.IP \(bu 2
+\fBAwesome\fP \- The pull request implements an especially well crafted
+solution, or a very difficult but necessary change.
+.IP \(bu 2
+\fBHelp Wanted\fP \- The issue appears to have a simple solution. Issues having
+this label should be a good starting place for new contributors to Salt.
+.IP \(bu 2
+\fBNeeds Testcase\fP \- The issue or pull request relates to a feature that
+needs test coverage. The pull request containing the tests should reference
+the issue or pull request having this label, whereupon the label should be
+removed.
+.IP \(bu 2
+\fBRegression\fP \- The issue is a bug that breaks functionality known to work
+in previous releases.
+.IP \(bu 2
+\fBStory\fP \- The issue is used by a SaltStack engineer to track progress on
+multiple related issues in a single place.
+.IP \(bu 2
+\fBStretch\fP \- The issue is an optional goal for the current sprint but may
+not be delivered.
+.IP \(bu 2
+\fBZD\fP \- The issue is related to a Zendesk customer support ticket.
+.IP \(bu 2
+\fB\fP \- The issue is scheduled to be implemented by \fB\fP\&.
+See here for a discussion of Salt\(aqs release
+codenames.
.UNINDENT
.SS Logging Internals
.sp
@@ -346316,6 +356348,15 @@ Edit the file you have selected, and verify that the changes are correct.
.ft C
$ vim salt/modules/alternatives.py
$ git diff
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
diff \-\-git a/salt/modules/alternatives.py b/salt/modules/alternatives.py
index 1653e5f..30c0a59 100644
\-\-\- a/salt/modules/alternatives.py
@@ -346555,6 +356596,7 @@ The default context provides the following properties
.sp
As well as any additional properties entered from the questions section of \fBtemplate.yml\fP
.SS API
+.SS salt.utils.extend module
.SS SaltStack Extend
.sp
A templating tool for extending SaltStack.
@@ -346568,11 +356610,7 @@ This tool is accessed using \fIsalt\-extend\fP
.INDENT 0.0
.TP
.B codeauthor
-
-.nf
-:email:\(gaAnthony Shaw \(ga
-.fi
-
+Anthony Shaw <\fI\%anthonyshaw@apache.org\fP>
.UNINDENT
.UNINDENT
.UNINDENT
@@ -347121,6 +357159,1303 @@ See implementation details in \fItests.support.helpers\fP for details.
.sp
\fI@with_system_user_and_group\fP \-\- Creates and optionally destroys a system user and group
within a test case. See implementation details in \fItests.support.helpers\fP for details.
+.SS Integration Tests
+.sp
+The Salt integration tests come with a number of classes and methods which
+allow for components to be easily tested. These classes are generally inherited
+from and provide specific methods for hooking into the running integration test
+environment created by the integration tests.
+.sp
+It is noteworthy that since integration tests validate against a running
+environment that they are generally the preferred means to write tests.
+.sp
+The integration system is all located under \fBtests/integration\fP in the Salt
+source tree. Each directory within \fBtests/integration\fP corresponds to a
+directory in Salt\(aqs tree structure. For example, the integration tests for the
+\fBtest.py\fP Salt module that is located in \fBsalt/modules\fP should also be
+named \fBtest.py\fP and reside in \fBtests/integration/modules\fP\&.
+.SS Preparing to Write Integration Tests
+.sp
+This guide assumes that your Salt development environment is already configured
+and that you have a basic understanding of contributing to the Salt codebase.
+If you\(aqre unfamiliar with either of these topics, please refer to the
+Installing Salt for Development and the
+Contributing pages, respectively.
+.sp
+This documentation also assumes that you have an understanding of how to
+run Salt\(aqs test suite, including running the
+test subsections, and running a single
+integration test file, class, or individual test.
+.SS Best Practices
+.sp
+Integration tests should be written to the following specifications.
+.SS What to Test?
+.sp
+Since integration tests are used to validate against a running Salt environment,
+integration tests should be written with the Salt components, and their various
+interactions, in mind.
+.INDENT 0.0
+.IP \(bu 2
+Isolate testing functionality. Don\(aqt rely on the pass or failure of other,
+separate tests.
+.IP \(bu 2
+Individual tests should test against a single behavior.
+.IP \(bu 2
+Since it occasionally takes some effort to "set up" an individual test, it may
+be necessary to call several functions within a single test. However, be sure
+that once the work has been done to set up a test, make sure you are clear
+about the functionality that is being tested.
+.UNINDENT
+.SS Naming Conventions
+.sp
+Test names and docstrings should indicate what functionality is being tested.
+Test functions are named \fBtest__\fP where \fB