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

Merge branch 'master' of github.com:thatch45/salt into highstate

Browse source
This commit is contained in:
Thomas S Hatch 2011-06-02 14:11:39 -06:00
commit 4f2899018a
55 changed files with 5483 additions and 321 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

28
AUTHORS Normal file
View file

@ -0,0 +1,28 @@
=============
Salt Authors
=============
Whos Who in Salt
============================
The Man With the Plan
----------------------------
Thomas S Hatch is the main developer of Salt. He is the founder, owner,
maintainer and lead of the Salt project, as well as author of the majority
of the Salt code and documentation.
Documentation System
----------------------------
The documentation system was put together by Seth House, much of the
documentation is being maintained by Seth
Developers
----------------------------
Pedro Algarvio, aka, s0undt3ch
Joseph P. Hall
Matthias Teege

50
README
View file

@ -1,50 +0,0 @@
What is Salt?
We’re not just talking about NaCl.
Salt is a distributed remote execution system used to execute commands and query
data. 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 via its ability to handle larger loads of information,
and not just dozens, but hundreds or even thousands of individual servers,
handle them quickly and through a simple and manageable interface.
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 disparate 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.
The core function of salt is to enable remote commands to be called in parallel
rather than in serial, to use a secure and encrypted protocol, the smallest and
fastest network payloads possible and with a simple programmer interface.
Salt also introduces more granular controls to the realm of remote execution,
allowing for commands to be executed in parallel and for systems to be targeted
based on more than just hostname, but by system properties.
Salt takes advantage of a number of technologies and techniques. The networking
layer is built with the excellent zeromq networking library, so salt itself
contains a viable, and transparent, amq broker inside the daemon. Salt uses
public keys for authentication with the master daemon, then uses faster aes
encryption for payload communication, this means that authentication and
encryption are also built into Salt. Salt takes advantage of communication via
python pickles, enabling fast and light network traffic.
In order to allow for simple expansion, Salt execution routines can be written
as plain python modules, and 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.
The result is a system that can execute commands across groups of varying size,
from very few to very many servers at considerably high speed. A system that is
very fast, easy to set up and amazingly malleable, able to suit the needs of any
number of servers working within the same system. Salt’s unique architecture
brings together the best of the remote execution world, amplifies its
capabilities and expands its range, resulting in this system that is as
versatile as it is practical, able to suit any network.
Salt is developed under the Apache 2.0 licence, and can be used for open and
proprietary projects. Please submit your expansions to back so that we can all
benefit together as Salt grows. So, please feel free to sprinkle some of this
around your systems and let the deliciousness come forth.

81
README.rst Normal file
View file

@ -0,0 +1,81 @@
=============
What is Salt?
=============
.. rubric:: We’re not just talking about NaCl.
Distributed remote execution
============================
Salt is a distributed remote execution system used to execute commands and
query data. 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 via its ability to handle larger loads of
information, and not just dozens, but hundreds or even thousands of individual
servers, handle them quickly and through a simple and manageable interface.
Simplicity
==========
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 disparate datacenters. 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.
Parallel execution
==================
The core function of Salt is to enable remote commands to be called in parallel
rather than in serial, to use a secure and encrypted protocol, the smallest and
fastest network payloads possible, and with a simple programmer interface. Salt
also introduces more granular controls to the realm of remote execution,
allowing for commands to be executed in parallel and for systems to be targeted
based on more than just hostname, but by system properties.
Building on proven technology
=============================
Salt takes advantage of a number of technologies and techniques. The networking
layer is built with the excellent `ZeroMQ`_ networking library, so Salt itself
contains a viable, and transparent, AMQ broker inside the daemon. Salt uses
public keys for authentication with the master daemon, then uses faster AES
encryption for payload communication, this means that authentication and
encryption are also built into Salt. Salt takes advantage of communication via
Python pickles, enabling fast and light network traffic.
.. _`ZeroMQ`: http://www.zeromq.org/
Python client interface
=======================
In order to allow for simple expansion, Salt execution routines can be written
as plain Python modules and 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.
Fast, flexible, scalable
========================
The result is a system that can execute commands across groups of varying size,
from very few to very many servers at considerably high speed. A system that is
very fast, easy to set up and amazingly malleable, able to suit the needs of
any number of servers working within the same system. Salt’s unique
architecture brings together the best of the remote execution world, amplifies
its capabilities and expands its range, resulting in this system that is as
versatile as it is practical, able to suit any network.
Open
====
Salt is developed under the `Apache 2.0 licence`_, 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. So, please feel free to
sprinkle some of this around your systems and let the deliciousness come forth.
.. _`Apache 2.0 licence`: http://www.apache.org/licenses/LICENSE-2.0.html

11
conf/master
View file

@ -49,6 +49,9 @@
# use and what modules to use. The state_top file is defined relative to the
# root of the base environment
#state_top: top.yml
#
# The renderer to use on the minions to render the state data
#renderer: yaml_jinja
##### File Server settings #####
##########################################
@ -62,18 +65,18 @@
# reliably ensured. A base environment is required to house the top file
# Example:
# file_roots:
# - base:
# base:
# - /srv/salt/
# - dev:
# dev:
# - /srv/salt/dev/services
# - /srv/salt/dev/states
# - prod:
# prod:
# - /srv/salt/prod/services
# - /srv/salt/prod/states
#
# Default:
#file_roots:
# - base:
# base:
# - /srv/salt
# The hash_type is the hash to use when discovering the hash of a file on

130
doc/Makefile Normal file
View file

@ -0,0 +1,130 @@
# Makefile for Sphinx documentation
#
# You can set these variables from the command line.
SPHINXOPTS =
SPHINXBUILD = sphinx-build
PAPER =
BUILDDIR = _build
# Internal variables.
PAPEROPT_a4 = -D latex_paper_size=a4
PAPEROPT_letter = -D latex_paper_size=letter
ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest
help:
@echo "Please use \`make <target>' where <target> is one of"
@echo " html to make standalone HTML files"
@echo " dirhtml to make HTML files named index.html in directories"
@echo " singlehtml to make a single large HTML file"
@echo " pickle to make pickle files"
@echo " json to make JSON files"
@echo " htmlhelp to make HTML files and a HTML help project"
@echo " qthelp to make HTML files and a qthelp project"
@echo " devhelp to make HTML files and a Devhelp project"
@echo " epub to make an epub"
@echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
@echo " latexpdf to make LaTeX files and run them through pdflatex"
@echo " text to make text files"
@echo " man to make manual pages"
@echo " changes to make an overview of all changed/added/deprecated items"
@echo " linkcheck to check all external links for integrity"
@echo " doctest to run all doctests embedded in the documentation (if enabled)"
clean:
-rm -rf $(BUILDDIR)/*
html:
$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
@echo
@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
dirhtml:
$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
@echo
@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
singlehtml:
$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
@echo
@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
pickle:
$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
@echo
@echo "Build finished; now you can process the pickle files."
json:
$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
@echo
@echo "Build finished; now you can process the JSON files."
htmlhelp:
$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
@echo
@echo "Build finished; now you can run HTML Help Workshop with the" \
".hhp project file in $(BUILDDIR)/htmlhelp."
qthelp:
$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
@echo
@echo "Build finished; now you can run "qcollectiongenerator" with the" \
".qhcp project file in $(BUILDDIR)/qthelp, like this:"
@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/Salt.qhcp"
@echo "To view the help file:"
@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/Salt.qhc"
devhelp:
$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
@echo
@echo "Build finished."
@echo "To view the help file:"
@echo "# mkdir -p $$HOME/.local/share/devhelp/Salt"
@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/Salt"
@echo "# devhelp"
epub:
$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
@echo
@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
latex:
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
@echo
@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
@echo "Run \`make' in that directory to run these through (pdf)latex" \
"(use \`make latexpdf' here to do that automatically)."
latexpdf:
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
@echo "Running LaTeX files through pdflatex..."
make -C $(BUILDDIR)/latex all-pdf
@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
text:
$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
@echo
@echo "Build finished. The text files are in $(BUILDDIR)/text."
man:
$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
@echo
@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
changes:
$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
@echo
@echo "The overview file is in $(BUILDDIR)/changes."
linkcheck:
$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
@echo
@echo "Link check complete; look for any errors in the above output " \
"or in $(BUILDDIR)/linkcheck/output.txt."
doctest:
$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
@echo "Testing of doctests in the sources finished, look at the " \
"results in $(BUILDDIR)/doctest/output.txt."

9
doc/_ext/saltdocs.py Normal file
View file

@ -0,0 +1,9 @@
def setup(app):
"""Additions and customizations to Sphinx that are useful for documenting
the Salt project.
"""
app.add_crossref_type(directivename="conf_master", rolename="conf_master",
indextemplate="pair: %s; conf/master")
app.add_crossref_type(directivename="conf_minion", rolename="conf_minion",
indextemplate="pair: %s; conf/minion")

215
doc/conf.py Normal file
View file

@ -0,0 +1,215 @@
# -*- coding: utf-8 -*-
import sys, os
docs_basepath = os.path.abspath(os.path.join(os.path.dirname(__file__)))
sys.path.extend([
os.path.join(docs_basepath, '..'), # salt directory (for autodoc)
os.path.join(docs_basepath, '_ext'), # Sphinx extensions
])
# -- General configuration -----------------------------------------------------
# If your documentation needs a minimal Sphinx version, state it here.
#needs_sphinx = '1.0'
# Add any Sphinx extension module names here, as strings. They can be extensions
# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
extensions = ['saltdocs', 'sphinx.ext.autodoc']
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
# The suffix of source filenames.
source_suffix = '.rst'
# The encoding of source files.
#source_encoding = 'utf-8-sig'
# The master toctree document.
master_doc = 'index'
# General information about the project.
project = u'Salt'
copyright = u'2011, Thomas S. Hatch'
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
# built documents.
#
# The short X.Y version.
version = '0.8.8'
# The full version, including alpha/beta/rc tags.
release = '0.8.8'
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
#language = None
# There are two options for replacing |today|: either, you set today to some
# non-false value, then it is used:
#today = ''
# Else, today_fmt is used as the format for a strftime call.
#today_fmt = '%B %d, %Y'
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
exclude_patterns = ['_build']
# The reST default role (used for this markup: `text`) to use for all documents.
#default_role = None
# If true, '()' will be appended to :func: etc. cross-reference text.
#add_function_parentheses = True
# If true, the current module name will be prepended to all description
# unit titles (such as .. function::).
#add_module_names = True
# If true, sectionauthor and moduleauthor directives will be shown in the
# output. They are ignored by default.
#show_authors = False
# The name of the Pygments (syntax highlighting) style to use.
pygments_style = 'sphinx'
# A list of ignored prefixes for module index sorting.
#modindex_common_prefix = []
# -- Options for HTML output ---------------------------------------------------
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
html_theme = 'default'
# Theme options are theme-specific and customize the look and feel of a theme
# further. For a list of options available for each theme, see the
# documentation.
#html_theme_options = {}
# Add any paths that contain custom themes here, relative to this directory.
#html_theme_path = []
# The name for this set of Sphinx documents. If None, it defaults to
# "<project> v<release> documentation".
#html_title = None
# A shorter title for the navigation bar. Default is the same as html_title.
#html_short_title = None
# The name of an image file (relative to this directory) to place at the top
# of the sidebar.
#html_logo = None
# The name of an image file (within the static path) to use as favicon of the
# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
# pixels large.
#html_favicon = None
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['_static']
# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
# using the given strftime format.
#html_last_updated_fmt = '%b %d, %Y'
# If true, SmartyPants will be used to convert quotes and dashes to
# typographically correct entities.
#html_use_smartypants = True
# Custom sidebar templates, maps document names to template names.
#html_sidebars = {}
# Additional templates that should be rendered to pages, maps page names to
# template names.
#html_additional_pages = {}
# If false, no module index is generated.
#html_domain_indices = True
# If false, no index is generated.
#html_use_index = True
# If true, the index is split into individual pages for each letter.
#html_split_index = False
# If true, links to the reST sources are added to the pages.
#html_show_sourcelink = True
# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
#html_show_sphinx = True
# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
#html_show_copyright = True
# If true, an OpenSearch description file will be output, and all pages will
# contain a <link> tag referring to it. The value of this option must be the
# base URL from which the finished HTML is served.
#html_use_opensearch = ''
# This is the file name suffix for HTML files (e.g. ".xhtml").
#html_file_suffix = None
# Output file base name for HTML help builder.
htmlhelp_basename = 'Saltdoc'
# -- Options for LaTeX output --------------------------------------------------
# The paper size ('letter' or 'a4').
#latex_paper_size = 'letter'
# The font size ('10pt', '11pt' or '12pt').
#latex_font_size = '10pt'
# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title, author, documentclass [howto/manual]).
latex_documents = [
('index', 'Salt.tex', u'Salt Documentation',
u'Thomas Hatch', 'manual'),
]
# The name of an image file (relative to this directory) to place at the top of
# the title page.
#latex_logo = None
# For "manual" documents, if this is true, then toplevel headings are parts,
# not chapters.
#latex_use_parts = False
# If true, show page references after internal links.
#latex_show_pagerefs = False
# If true, show URL addresses after external links.
#latex_show_urls = False
# Additional stuff for the LaTeX preamble.
#latex_preamble = ''
# Documents to append as an appendix to all manuals.
#latex_appendices = []
# If false, no module index is generated.
#latex_domain_indices = True
# -- Options for manual page output --------------------------------------------
# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
authors = [
u'Thomas S. Hatch <thatch@gmail.com> and many others, please see the Authors file',
]
man_pages = [
('ref/cli/salt', 'salt', u'salt', authors, 1),
('index', 'salt', u'Salt Documentation', authors, 7),
('ref/cli/salt-master', 'salt-master', u'salt-master Documentation', authors, 1),
('ref/cli/salt-minion', 'salt-minion', u'salt-minion Documentation', authors, 1),
('ref/cli/salt-key', 'salt-key', u'salt-key Documentation', authors, 1),
('ref/cli/salt-cp', 'salt-cp', u'salt-cp Documentation', authors, 1),
]

81
doc/index.rst Normal file
View file

@ -0,0 +1,81 @@
.. _index:
====
Salt
====
.. rubric:: Simplified system communication
Salt is a powerful remote execution manager that can be used to administer
servers in a fast and efficient way.
Getting started
===============
.. sidebar:: Getting help
* Watch a presentation on Salt: `video`_ | `slides`_ (PDF)
* Join the `salt-users mailing list`_, it is the best place to ask
questions about Salt and see whats going on with Salt development!
* Report any bugs on the `GitHub issues page`_.
.. _`video`: http://blip.tv/thomas-s-hatch/salt-0-8-7-presentation-5180182
.. _`slides`: https://github.com/downloads/thatch45/salt/Salt.pdf
.. _`salt-users mailing list`: http://groups.google.com/group/salt-users
.. _`GitHub issues page`: https://github.com/thatch45/salt/issues
New users should start here
.. toctree::
:maxdepth: 1
topics/index
topics/tutorial
Using Salt
==========
.. toctree::
:maxdepth: 1
ref/configuration/index
ref/cli/index
Extending Salt
==============
Writing your own customizations on top of Salt
.. toctree::
:maxdepth: 1
ref/index
ref/python-api
ref/modules/index
ref/returners/index
ref/grains
ref/renderers
ref/states
Getting involved
================
.. toctree::
:maxdepth: 1
topics/community
topics/releases/index
Indices, glossary and tables
============================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

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

@ -1,51 +1,106 @@
.TH salt-cp 1 "May 2011" "salt 0.8.7" "salt-cp Manual"
.TH "SALT-CP" "1" "May 30, 2011" "0.8.8" "Salt"
.SH NAME
salt-cp \- Copy a file to a set of systems
salt-cp \- salt-cp Documentation
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.\" Man page generated from reStructeredText.
.
.sp
Copy a file to a set of systems
.SH SYNOPSIS
.B salt-cp '*' [ options ] \fISOURCE DEST\fR
.sp
.nf
.ft C
salt\-cp \(aq*\(aq [ options ] SOURCE DEST
.B salt-cp -E '.*' [ options ] \fISOURCE DEST\fR
.B salt-cp -G 'os:Arch.*' [ options ] \fISOURCE DEST\fR
salt\-cp \-E \(aq.*\(aq [ options ] SOURCE DEST
salt\-cp \-G \(aqos:Arch.*\(aq [ options ] SOURCE DEST
.ft P
.fi
.SH DESCRIPTION
Salt copy copies a local file out to all of the salt minions matched by the given target.
.sp
Salt copy copies a local file out to all of the salt minions matched by the
given target.
.SH OPTIONS
.INDENT 0.0
.TP
-h, --help
Print a usage message briefly summarizing these command-line options
.B \-h, \-\-help
.sp
Print a usage message briefly summarizing these command\-line options
.UNINDENT
.INDENT 0.0
.TP
-t TIMEOUT, --timeout=TIMEOUT
.B \-t TIMEOUT, \-\-timeout=TIMEOUT
.sp
The timeout in seconds to wait for replies from the salt minions.
.UNINDENT
.INDENT 0.0
.TP
-E, --pcre
The target expression will be interpreted as a pcre regular expression rather than a shell glob.
.B \-E, \-\-pcre
.sp
The target expresion will be interpereted as a pcre regular expression
rather than a shell glob.
.UNINDENT
.INDENT 0.0
.TP
-L, --list
The target expression will be interpreted as a comma delimited list,
.B \-L, \-\-list
.sp
The target expression will be interpereted as a comma delimited list,
example: server1.foo.bar,server2.foo.bar,example7.quo.qux
.UNINDENT
.INDENT 0.0
.TP
-G, --grain
The target expression matches values returned by the salt grains system on the
minions. The target expression is in the format of '<grain value>:<pcre regular expression>';
example: 'os:Arch.*'
.B \-G, \-\-grain
.sp
The target expression matches values returned by the salt grains system on
the minions. The target expresion is in the format of \(aq<grain value>:<pcre
regular expresion>\(aq; example: \(aqos:Arch.*\(aq
.UNINDENT
.INDENT 0.0
.TP
-Q, --query
Execute a salt command query, this can be used to find the results os a previous
function call: -Q test.echo')
.B \-Q, \-\-query
.sp
Execute a salt command query, this can be used to find the results os a
previous function call: \-Q test.echo\(aq)
.UNINDENT
.INDENT 0.0
.TP
-c CONFIG, --config=CONFIG
The location of the salt master configuration file, the salt master settings are
required to know where the connections are; default=/etc/salt/master
.SH AUTHORS
Thomas S. Hatch <thatch@gmail.com>
.B \-c CONFIG, \-\-config=CONFIG
.sp
The location of the salt master configuration file, the salt master
settings are required to know where the connections are;
default=/etc/salt/master
.UNINDENT
.SH AUTHOR
Thomas S. Hatch <thatch@gmail.com> and many others, please see the Authors file
.SH COPYRIGHT
2011, Thomas Hatch
.\" Generated by docutils manpage writer.
.\"
.

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

@ -1,40 +1,86 @@
.TH salt-key 1 "May 2011" "salt-key 0.8.7" "salt-key Manual"
.TH "SALT-KEY" "1" "May 30, 2011" "0.8.8" "Salt"
.SH NAME
salt-key \- Public key management for salt
salt-key \- salt-key Documentation
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.\" Man page generated from reStructeredText.
.
.SH SYNOPSIS
.B salt-key [ options ]
.sp
salt\-key [ options ]
.SH DESCRIPTION
Salt-key executes simple management of salt server public keys used for authentication.
.sp
Salt\-key executes simple management of salt server public keys used for
authentication.
.SH OPTIONS
.INDENT 0.0
.TP
-h, --help
Print a usage message briefly summarizing these command-line options.
.B \-h, \-\-help
.sp
Print a usage message briefly summarizing these command\-line options.
.UNINDENT
.INDENT 0.0
.TP
-l, --list
.B \-l, \-\-list
.sp
List the unaccepted minion public keys.
.UNINDENT
.INDENT 0.0
.TP
-L, --list-all
List all public keys on this salt master, both accepted and pending acceptance.
.B \-L, \-\-list\-all
.sp
List all public keys on this salt master, both accepted and pending
acceptance.
.UNINDENT
.INDENT 0.0
.TP
-a ACCEPT, --accept=ACCEPT
.B \-a ACCEPT, \-\-accept=ACCEPT
.sp
Accept the named minion public key for command execution.
.UNINDENT
.INDENT 0.0
.TP
-A, --accept-all
.B \-A, \-\-accept\-all
.sp
Accepts all pending public keys.
.UNINDENT
.INDENT 0.0
.TP
-c CONFIG, --config=CONFIG
The master configuration file needs to be read to determine where the salt keys
are stored via the pki_dir configuration value; default=/etc/salt/master
.SH AUTHORS
Thomas S. Hatch <thatch@gmail.com>
.B \-c CONFIG, \-\-config=CONFIG
.sp
The master configuration file needs to be read to determine where the salt
keys are stored via the pki_dir configuration value;
default=/etc/salt/master
.UNINDENT
.SH AUTHOR
Thomas S. Hatch <thatch@gmail.com> and many others, please see the Authors file
.SH COPYRIGHT
2011, Thomas Hatch
.\" Generated by docutils manpage writer.
.\"
.

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

@ -1,27 +1,66 @@
.TH salt-master 1 "May 2011" "salt-master 0.8.7" "salt-master Manual"
.TH "SALT-MASTER" "1" "May 30, 2011" "0.8.8" "Salt"
.SH NAME
salt-master \- The salt master daemon, used to control the salt minions
salt-master \- salt-master Documentation
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.\" Man page generated from reStructeredText.
.
.sp
The salt master daemon, used to control the salt minions
.SH SYNOPSIS
.B salt-master [ options ]
.sp
salt\-master [ options ]
.SH DESCRIPTION
.sp
The master daemon controls the salt minions
.SH OPTIONS
.INDENT 0.0
.TP
-h, --help
Print a usage message briefly summarizing these command-line options.
.B \-h, \-\-help
.sp
Print a usage message briefly summarizing these command\-line options.
.UNINDENT
.INDENT 0.0
.TP
-d, --daemon
.B \-d, \-\-daemon
.sp
Run the salt master as a daemon
.UNINDENT
.INDENT 0.0
.TP
-c CONFIG, --config=CONFIG
.B \-c CONFIG, \-\-config=CONFIG
.sp
The master configuration file to use, the default is /etc/salt/master
.SH AUTHORS
Thomas S. Hatch <thatch@gmail.com>
.UNINDENT
.SH AUTHOR
Thomas S. Hatch <thatch@gmail.com> and many others, please see the Authors file
.SH COPYRIGHT
2011, Thomas Hatch
.\" Generated by docutils manpage writer.
.\"
.

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

@ -1,30 +1,67 @@
.TH salt-minion 1 "May 2011" "salt-minion 0.8.7" "salt-minion Manual"
.TH "SALT-MINION" "1" "May 30, 2011" "0.8.8" "Salt"
.SH NAME
salt-minion \- The salt minion daemon, receives commands from a remote salt master.
salt-minion \- salt-minion Documentation
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.\" Man page generated from reStructeredText.
.
.sp
The salt minion daemon, recieves commands from a remote salt master.
.SH SYNOPSIS
.B salt-minion [ options ]
.sp
salt\-minion [ options ]
.SH DESCRIPTION
The salt minion receives commands from the central salt master and replies with
.sp
The salt minion recieves commands from the central salt master and replies with
the results of said commands.
.SH OPTIONS
.INDENT 0.0
.TP
-h, --help
Print a usage message briefly summarizing these command-line options.
.B \-h, \-\-help
.sp
Print a usage message briefly summarizing these command\-line options.
.UNINDENT
.INDENT 0.0
.TP
-d, --daemon
.B \-d, \-\-daemon
.sp
Run the salt minion as a daemon
.UNINDENT
.INDENT 0.0
.TP
-c CONFIG, --config=CONFIG
.B \-c CONFIG, \-\-config=CONFIG
.sp
The minion configuration file to use, the default is /etc/salt/minion
.SH AUTHORS
Thomas S. Hatch <thatch@gmail.com>
.P
Joseph Hall <perlhoser@gmail.com>
.UNINDENT
.SH AUTHOR
Thomas S. Hatch <thatch@gmail.com> and many others, please see the Authors file
.SH COPYRIGHT
2011, Thomas Hatch
.\" Generated by docutils manpage writer.
.\"
.

139
doc/man/salt.1
View file

@ -1,55 +1,112 @@
.TH salt 1 "May 2011" "salt 0.8.7" "salt Manual"
.TH "SALT" "1" "May 30, 2011" "0.8.8" "Salt"
.SH NAME
salt \- Parallel remote execution system
salt \- salt
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.\" Man page generated from reStructeredText.
.
.SH SYNOPSIS
.B salt '*' [ options ] sys.doc
.B salt -E '.*' [ options ] sys.doc cmd
.B salt -F 'operatingsystem:Arch.*' [ options ] test.ping
.B salt -Q test.ping
.INDENT 0.0
.INDENT 3.5
.sp
salt \(aq*\(aq [ options ] sys.doc
.sp
salt \-E \(aq.*\(aq [ options ] sys.doc cmd
.sp
salt \-F \(aqoperatingsystem:Arch.*\(aq [ options ] test.ping
.sp
salt \-Q test.ping
.UNINDENT
.UNINDENT
.SH DESCRIPTION
Salt allows for commands to be executed across a swath of remote systems in parallel.
This means that remote systems can be both controlled and queried with ease.
.sp
Salt allows for commands to be executed across a swath of remote systems in
parallel. This means that remote systems can be both controlled and queried
with ease.
.SH OPTIONS
.INDENT 0.0
.TP
-h, --help
Print a usage message briefly summarizing these command-line options
.B \-h, \-\-help
.sp
Print a usage message briefly summarizing these command\-line options
.UNINDENT
.INDENT 0.0
.TP
-t TIMEOUT, --timeout=TIMEOUT
.B \-t TIMEOUT, \-\-timeout=TIMEOUT
.sp
The timeout in seconds to wait for replies from the salt minions.
.UNINDENT
.INDENT 0.0
.TP
-E, --pcre
The target expression will be interpreted as a pcre regular expression rather than
a shell glob.
.B \-E, \-\-pcre
.sp
The target expression will be interpreted as a pcre regular expression
rather than a shell glob.
.UNINDENT
.INDENT 0.0
.TP
-L, --list
.B \-L, \-\-list
.sp
The target expression will be interpreted as a comma delimited list,
example: server1.foo.bar,server2.foo.bar,example7.quo.qux
.UNINDENT
.INDENT 0.0
.TP
-G, --grain
The target expression matches values returned by the salt grains system on the
minions. The target expression is in the format of '<grain value>:<pcre regular expression>';
example: 'os:Arch.*'
.B \-G, \-\-grain
.sp
The target expression matches values returned by the salt grains system on
the minions. The target expression is in the format of \(aq<grain value>:<pcre
regular expression>\(aq; example: \(aqos:Arch.*\(aq
.UNINDENT
.INDENT 0.0
.TP
-Q, --query
Execute a salt command query, this can be used to find the results os a previous
function call: -Q test.echo')
.B \-Q, \-\-query
.sp
Execute a salt command query, this can be used to find the results os a
previous function call: \-Q test.echo\(aq)
.UNINDENT
.INDENT 0.0
.TP
-c CONFIG, --config=CONFIG
The location of the salt master configuration file, the salt master settings are
required to know where the connections are; default=/etc/salt/master
.SH AUTHORS
Thomas S. Hatch <thatch@gmail.com>
.B \-c CONFIG, \-\-config=CONFIG
.sp
The location of the salt master configuration file, the salt master
settings are required to know where the connections are;
default=/etc/salt/master
.UNINDENT
.SH SEE ALSO
.sp
\fIsalt(7)\fP
\fIsalt\-master(1)\fP
\fIsalt\-minion(1)\fP
.SH AUTHOR
Thomas S. Hatch <thatch@gmail.com> and many others, please see the Authors file
.SH COPYRIGHT
2011, Thomas Hatch
.\" Generated by docutils manpage writer.
.\"
.

2173
doc/man/salt.7
View file

File diff suppressed because it is too large Load diff

66
doc/ref/cli/index.rst Normal file
View file

@ -0,0 +1,66 @@
======================
Command line reference
======================
.. toctree::
:maxdepth: 1
salt
salt-master
salt-minion
salt-key
salt-cp
salt-call
Salt can be controlled by a command line client as root 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.
Using the Salt client commands can be easily sent to the minions.
Using the Salt Command
======================
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.
Defining the Target Minions
---------------------------
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:
.. code-block:: bash
salt '*foo.com' sys.doc
Salt can also define the target minions with regular expressions:
.. code-block:: bash
salt -E '.*' cmd.run 'ls -l | grep foo'
Or to explicitly list hosts, salt can take a list:
.. code-block:: bash
salt -L foo.bar.baz,quo.qux cmd.run 'ps aux | grep foo'
Calling the function
--------------------
The function to call on the specified target is placed after the target
specification.
Finding available minion functions
``````````````````````````````````
The Salt functions are self documenting, all of the function documentation can
be retried from the minions via the :func:`sys.doc` function:
.. code-block:: bash
salt '*' sys.doc

33
doc/ref/cli/salt-call.rst Normal file
View file

@ -0,0 +1,33 @@
=============
``salt-call``
=============
Synopsis
========
::
salt-call [options]
Options
=======
.. program:: salt-call
.. option:: -h, --help
Print a usage message briefly summarizing these command-line options
.. option:: -g, --grains
Return the information generated by the salt grains
.. option:: -m MODULE_DIRS, --module-dirs=MODULE_DIRS
Specify an additional directories to pull modules from, multiple
directories can be delimited by commas
.. option:: -d, --doc
Return the documentation for the specified module of for all modules if
none are specified

62
doc/ref/cli/salt-cp.rst Normal file
View file

@ -0,0 +1,62 @@
===========
``salt-cp``
===========
Copy a file to a set of systems
Synopsis
========
::
salt-cp '*' [ options ] SOURCE DEST
salt-cp -E '.*' [ options ] SOURCE DEST
salt-cp -G 'os:Arch.*' [ options ] SOURCE DEST
Description
===========
Salt copy copies a local file out to all of the salt minions matched by the
given target.
Options
=======
.. program:: salt-cp
.. option:: -h, --help
Print a usage message briefly summarizing these command-line options
.. option:: -t TIMEOUT, --timeout=TIMEOUT
The timeout in seconds to wait for replies from the salt minions.
.. option:: -E, --pcre
The target expresion will be interpereted as a pcre regular expression
rather than a shell glob.
.. option:: -L, --list
The target expression will be interpereted as a comma delimited list,
example: server1.foo.bar,server2.foo.bar,example7.quo.qux
.. option:: -G, --grain
The target expression matches values returned by the salt grains system on
the minions. The target expresion is in the format of '<grain value>:<pcre
regular expresion>'; example: 'os:Arch.*'
.. option:: -Q, --query
Execute a salt command query, this can be used to find the results os a
previous function call: -Q test.echo')
.. option:: -c CONFIG, --config=CONFIG
The location of the salt master configuration file, the salt master
settings are required to know where the connections are;
default=/etc/salt/master

46
doc/ref/cli/salt-key.rst Normal file
View file

@ -0,0 +1,46 @@
============
``salt-key``
============
Synopsis
========
salt-key [ options ]
Description
===========
Salt-key executes simple management of salt server public keys used for
authentication.
Options
=======
.. program:: salt-key
.. option:: -h, --help
Print a usage message briefly summarizing these command-line options.
.. option:: -l, --list
List the unaccepted minion public keys.
.. option:: -L, --list-all
List all public keys on this salt master, both accepted and pending
acceptance.
.. option:: -a ACCEPT, --accept=ACCEPT
Accept the named minion public key for command execution.
.. option:: -A, --accept-all
Accepts all pending public keys.
.. option:: -c CONFIG, --config=CONFIG
The master configuration file needs to be read to determine where the salt
keys are stored via the pki_dir configuration value;
default=/etc/salt/master

32
doc/ref/cli/salt-master.rst Normal file
View file

@ -0,0 +1,32 @@
===============
``salt-master``
===============
The salt master daemon, used to control the salt minions
Synopsis
========
salt-master [ options ]
Description
===========
The master daemon controls the salt minions
Options
=======
.. program:: salt-master
.. option:: -h, --help
Print a usage message briefly summarizing these command-line options.
.. option:: -d, --daemon
Run the salt master as a daemon
.. option:: -c CONFIG, --config=CONFIG
The master configuration file to use, the default is /etc/salt/master

33
doc/ref/cli/salt-minion.rst Normal file
View file

@ -0,0 +1,33 @@
===============
``salt-minion``
===============
The salt minion daemon, recieves commands from a remote salt master.
Synopsis
========
salt-minion [ options ]
Description
===========
The salt minion recieves commands from the central salt master and replies with
the results of said commands.
Options
=======
.. program:: salt-minion
.. option:: -h, --help
Print a usage message briefly summarizing these command-line options.
.. option:: -d, --daemon
Run the salt minion as a daemon
.. option:: -c CONFIG, --config=CONFIG
The minion configuration file to use, the default is /etc/salt/minion

68
doc/ref/cli/salt.rst Normal file
View file

@ -0,0 +1,68 @@
========
``salt``
========
Synopsis
========
salt '*' [ options ] sys.doc
salt -E '.*' [ options ] sys.doc cmd
salt -F 'operatingsystem:Arch.*' [ options ] test.ping
salt -Q test.ping
Description
===========
Salt allows for commands to be executed across a swath of remote systems in
parallel. This means that remote systems can be both controlled and queried
with ease.
Options
=======
.. program:: salt
.. option:: -h, --help
Print a usage message briefly summarizing these command-line options
.. option:: -t TIMEOUT, --timeout=TIMEOUT
The timeout in seconds to wait for replies from the salt minions.
.. option:: -E, --pcre
The target expression will be interpreted as a pcre regular expression
rather than a shell glob.
.. option:: -L, --list
The target expression will be interpreted as a comma delimited list,
example: server1.foo.bar,server2.foo.bar,example7.quo.qux
.. option:: -G, --grain
The target expression matches values returned by the salt grains system on
the minions. The target expression is in the format of '<grain value>:<pcre
regular expression>'; example: 'os:Arch.*'
.. option:: -Q, --query
Execute a salt command query, this can be used to find the results os a
previous function call: -Q test.echo')
.. option:: -c CONFIG, --config=CONFIG
The location of the salt master configuration file, the salt master
settings are required to know where the connections are;
default=/etc/salt/master
See also
========
:manpage:`salt(7)`
:manpage:`salt-master(1)`
:manpage:`salt-minion(1)`

25
doc/ref/configuration/examples.rst Normal file
View file

@ -0,0 +1,25 @@
===========================
Configuration file examples
===========================
.. _configuration-examples-master:
.. contents::
:local:
:depth: 1
Example master configuration file
=================================
.. literalinclude:: ../../../conf/master
:language: ini
:linenos:
.. _configuration-examples-minion:
Example minion configuration file
=================================
.. literalinclude:: ../../../conf/minion
:language: ini
:linenos:

430
doc/ref/configuration/index.rst Normal file
View file

@ -0,0 +1,430 @@
===================
Configuration guide
===================
The Salt system is amazingly simple and easy to configure, the two components
of the Salt system each have a respective configuration file. The
:command:`salt-master` is configured via the master configuration file, and the
:command:`salt-minion` is configured via the minion configuration file.
.. toctree::
:hidden:
examples
.. seealso::
:ref:`example master configuration file <configuration-examples-master>`
|
:ref:`example minion configuration file <configuration-examples-minion>`
Configuring the Salt Master
===========================
The configuration file for the salt-master is located at
:file:`/etc/salt/master`. The available options are as follows:
Primary Master Configuration
----------------------------
.. conf_master:: interface
``interface``
-------------
Default: ``0.0.0.0`` (all interfaces)
The local interface to bind to.
.. code-block:: yaml
interface: 192.168.0.1
.. conf_master:: publish_port
``publish_port``
----------------
Default: ``4505``
The network port to set up the publication interface
.. code-block:: yaml
publish_port: 4505
.. conf_master:: publish_port
``publish_pull_port``
----------------
Default: ``45055``
The port used to communicate to the local publisher
.. code-block:: yaml
publish_pull_port: 45055
.. conf_master:: worker_threads
``worker_threads``
------------------
Default: ``5``
The number of threads to start for receiving commands and replies from minions.
If minions are stalling on replies because you have many minions, raise the
worker_threads value.
.. code-block:: yaml
worker_threads: 5
``worker_start_port``
------------------
Default: ``5``
The port to begin binding workers on, the workers will be created on
increasingly higher ports
.. code-block:: yaml
worker_start_port: 45056
.. conf_master:: ret_port
``ret_port``
------------
Default: ``4506``
The port used by the return server, this is the server used by Salt to receive
execution returns and command executions.
.. code-block:: yaml
ret_port: 4506
.. conf_master:: pki_dir
``pki_dir``
-----------
Default: :file:`/etc/salt/pki`
The directory to store the pki authentication keys.
.. code-block:: yaml
pki_dir: /etc/salt/pki
.. conf_master:: cachedir
``cachedir``
------------
Default: :file:`/var/cache/salt`
The location used to store cache information, particularly the job information
for executed salt commands.
.. code-block:: yaml
cachedir: /var/cache/salt
.. conf_master:: keep_jobs
``keep_jobs``
-------------
Default: ``24``
Set the number of hours to keep old job information
Master Security Settings
------------------------
.. conf_master:: open_mode
``open_mode``
-------------
Default: ``False``
Open mode is a dangerous security feature. One problem encountered with pki
authentication systems is that keys can become "mixed up" and authentication
begins to fail. Open mode turns off authentication and tells the master to
accept all authentication. This will clean up the pki keys recieved from the
minions. Open mode should not be turned on for general use, open mode should
only be used for a short period of time to clean up pki keys. To turn on open
mode the value passed must be ``True``.
.. code-block:: yaml
open_mode: False
.. conf_master:: auto_accept
``auto_accept``
---------------
Default: ``False``
Enable auto_accept, this setting will automatically accept all incoming
public keys from the minions
.. code_block:: yaml
auto_accept: False
Master State System Settings
---------------------------
.. conf_master:: state_top
``state_top``
-------------
Default: ``top.yml``
The state system uses a "top" file to tell the minions what environment to
use and what modules to use. The state_top file is defined relative to the
root of the base environment
.. code_block:: yaml
state_top: top.yml
.. conf_master:: renderer
``renderer``
------------
Default: ``yaml_jinja``
The renderer to use on the minions to render the state data
.. code_block:: yaml
renderer: yaml_jinja
Master File Server Settings
---------------------------
.. conf_master:: file_roots
``file_roots``
--------------
Default: ``base: [/srv/salt]``
Salt runs a lightweight file server written in zeromq to deliver files to
minions. This file server is built into the master daemon and does not
require a dedicated port.
The file server works on environments passed to the master, each environment
can have multiple root directories, the subdirectories in the multiple file
roots cannot match, otherwise the downloaded files will not be able to be
reliably ensured. A base environment is required to house the top file
Example:
file_roots:
base:
- /srv/salt/
dev:
- /srv/salt/dev/services
- /srv/salt/dev/states
prod:
- /srv/salt/prod/services
- /srv/salt/prod/states
.. code_block:: yaml
base:
- /srv/salt
.. conf_master:: hash_type
``hash_type``
-------------
Default: ``md5``
The hash_type is the hash to use when discovering the hash of a file on
the master server, the default is md5, but sha1, sha224, sha256, sha384
and sha512 are also supported.
.. code_block:: yaml
hash_type: md5
.. conf_master:: file_buffer_size
``file_buffer_size``
--------------------
Default: ``1048576``
The buffer size in the file server in bytes
.. code_block:: yaml
file_buffer_size: 1048576
Master Logging Settings
-----------------------
.. conf_master:: log_file
``log_file``
------------
Default: :file:`/etc/salt/pki`
The location of the master log file
.. code_block:: yaml
log_file: /var/log/salt/master
.. conf_master:: log_level
``log_level``
-------------
Default: ``warning``
The level of messages to send to the log file.
One of 'info', 'quiet', 'critical', 'error', 'debug', 'warning'.
.. code_block:: yaml
log_level: warning
.. conf_master:: log_granular_levels
``log_granular_levels``
-----------------------
Default: ``{}``
Logger levels can be used to tweak specific loggers logging levels.
Imagine you want to have the salt library at the 'warning' level, but, you
still wish to have 'salt.modules' at the 'debug' level:
log_granular_levels: {
'salt': 'warning',
'salt.modules': 'debug'
}
Configuring the Salt Minion
===========================
The Salt Minion configuration is very simple, typically the only value that
needs to be set is the master value so the minion can find its master.
Minion Primary Configuration
----------------------------
.. conf_minion:: master
``master``
----------
Default: ``salt``
The hostname or ipv4 of the master.
.. code-block:: yaml
master: salt
.. conf_minion:: master_port
``master_port``
---------------
Default: ``4506``
The port of the master ret server, this needs to coincide with the ret_port
option on the salt master.
.. code-block:: yaml
master_port: 4506
.. conf_minion:: pki_dir
``pki_dir``
-----------
Default: :file:`/etc/salt/pki`
The directory used to store the minion's public and private keys.
.. code-block:: yaml
pki_dir: /etc/salt/pki
.. conf_minion:: hostname
``id``
------------
Default: hostname (as returned by the Python call: ``socket.getfqdn()``)
Explicitly declare the id for this minion to use, if left commented the id
will be the hostname as returned by the python call: socket.getfqdn()
Since salt uses detached ids it is possible to run multiple minions on the
same machine but with different ids, this can be useful for salt compute
clusters.
.. code-block:: yaml
id: foo.bar.com
.. conf_minion:: cachedir
``cachedir``
------------
Default: :file:`/var/cache/salt`
The location for minion cache data.
.. code-block:: yaml
cachedir: /var/cache/salt
Minion Module Management
------------------------
.. conf_minion:: disable_modules
``disable_modules``
-------------------
Default: ``[]`` (all modules are enabled by default)
The event may occur in which the administrator desires that a minion should not
be able to execute a certain module. The sys module is built into the minion
and cannot be disabled.
.. code-block:: yaml
disable_modules: [cmd,virt,test]
.. conf_minion:: open_mode
``open_mode``
-------------
Default: ``False``
Open mode can be used to clean out the pki key recieved from the salt master,
turn on open mode, restart the minion, then turn off open mode and restart the
minion to clean the keys.
.. code-block:: yaml
open_mode: False

5
doc/ref/grains.rst Normal file
View file

@ -0,0 +1,5 @@
======
Grains
======
Static information that Salt derives about the system it's running on.

3
doc/ref/index.rst Normal file
View file

@ -0,0 +1,3 @@
==============================
Introduction to extending Salt
==============================

128
doc/ref/modules/index.rst Normal file
View file

@ -0,0 +1,128 @@
=======
Modules
=======
Salt modules are the functions called by the :command:`salt` command.
Full list of builtin modules
============================
.. toctree::
:maxdepth: 1
:glob:
*
Easy Modules to write
=====================
Salt modules are amazingly simple to write, just write a regular Python module
or a regular Cython module and place it in the ``salt/modules`` directory.
Since Salt modules are just Python/Cython modules there are no restraints as to
what you can put inside of a salt module, and if a Salt module has errors and
cannot import the Salt minion will continue to load without issue, the module
with errors will simply be omitted.
If adding a Cython module the file must be named ``<modulename>.pyx`` 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 ``*.pyx`` file is required.
Preloaded Modules Data
======================
When interacting with modules often it is nice to be able to read information
dynamically about the minion, or load in configuration parameters for a module.
Salt allows for different types of data to be loaded into the modules by the
minion, as of this writing Salt loads information gathered from the Salt Grains
system and from the minion configuration file.
Grains Data
-----------
The Salt minion detects information about the system when started. This allows
for modules to be written dynamically with respect to the underlying hardware
and OS. This information is referred to as Salt Grains, or "grains of salt".
The Grains system was introduced to replace Facter, since relying on a Ruby
application from a Python application was both slow and inefficient. Grains
support replaces Facter in all releases after 0.8
The values detected by the Salt Grains on the minion are available in a dict by
the name of ``__grains__`` and can be accessed from within callable objects in
the Python modules.
To see the contents of the grains dict for a given system in your deployment
run the :func:`grains.items` function:
.. code-block:: bash
salt 'hostname' grains.items
To use the ``__grains__`` dict simply call it as a Python dict from within your
code, an excellent example is available in the Grains module:
:mod:`salt.modules.grains`.
Module Configuration
--------------------
Since parameters for configuring a module may be desired, Salt allows for
configuration information stored in the main minion config file to be passed to
the modules.
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
**strongly** recommended that the values passed in the configuration file match
the module. This means that a value intended for the ``test`` module should be
named ``test.<value>``.
Configuration also requires that default configuration parameters need to be
loaded as well. This can be done simply by adding the ``__opts__`` dict to the
top level of the module.
The test 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. :mod:`salt.modules.test`, :file:`conf/minion`.
Documentation
=============
Salt modules are self documenting, the :func:`sys.doc` function will return the
documentation for all available Facter modules:
.. code-block:: bash
salt '*' sys.doc
This function simple prints out the docstrings found in the modules, when
writing salt modules, please follow the formating conventions for docstrings as
they appear in the other modules.
How Functions are Read
======================
In Salt Python callable objects contained within a 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 ``_``.
Objects Loaded Into the Salt Minion
-----------------------------------
.. code-block:: python
def foo(bar):
return bar
class baz:
def __init__(self, quo):
return quo
Objects NOT Loaded into the Salt Minion
---------------------------------------
.. code-block:: python
def _foobar(baz): # Preceded with an _
return baz
cheese = {} # Not a callable python object

125
doc/ref/modules/modules.rst Normal file
View file

@ -0,0 +1,125 @@
=============================
:mod:`salt.modules.butterkvm`
=============================
.. automodule:: salt.modules.butterkvm
:members:
===========================
:mod:`salt.modules.cluster`
===========================
.. automodule:: salt.modules.cluster
:members:
=======================
:mod:`salt.modules.cmd`
=======================
.. automodule:: salt.modules.cmd
:members:
========================
:mod:`salt.modules.cmdc`
========================
.. automodule:: salt.modules.cmdc
:members:
======================
:mod:`salt.modules.cp`
======================
.. automodule:: salt.modules.cp
:members:
===========================
:mod:`salt.modules.cytestx`
===========================
.. automodule:: salt.modules.cytestx
:members:
========================
:mod:`salt.modules.disk`
========================
.. automodule:: salt.modules.disk
:members:
==========================
:mod:`salt.modules.grains`
==========================
.. automodule:: salt.modules.grains
:members:
===========================
:mod:`salt.modules.network`
===========================
.. automodule:: salt.modules.network
:members:
==========================
:mod:`salt.modules.pacman`
==========================
.. automodule:: salt.modules.pacman
:members:
===========================
:mod:`salt.modules.service`
===========================
.. automodule:: salt.modules.service
:members:
=========================
:mod:`salt.modules.state`
=========================
.. automodule:: salt.modules.state
:members:
==========================
:mod:`salt.modules.status`
==========================
.. automodule:: salt.modules.status
:members:
===========================
:mod:`salt.modules.statusc`
===========================
.. automodule:: salt.modules.statusc
:members:
==========================
:mod:`salt.modules.sysctl`
==========================
.. automodule:: salt.modules.sysctl
:members:
========================
:mod:`salt.modules.test`
========================
.. automodule:: salt.modules.test
:members:
========================
:mod:`salt.modules.virt`
========================
.. automodule:: salt.modules.virt
:members:
=======================
:mod:`salt.modules.yum`
=======================
.. automodule:: salt.modules.yum
:members:

60
doc/ref/python-api.rst Normal file
View file

@ -0,0 +1,60 @@
=================
Python client API
=================
Salt is written to be completely API centric, Salt minions and master can be
built directly into third party applications as a communication layer. The Salt
client API is very straightforward.
Using the LocalClient API
=========================
Sending information through the client is simple:
.. code-block:: python
# Import the salt client librairy
import salt.client
# create a local client object
client = salt.client.LocalClient()
# make calls with the cmd method
ret = client.cmd('*', 'cmd.run', ['ls -l'])
The cmd call is the only one needed for the local client, the arguments are as
follows:
.. function:: LocalClient.cmd(tgt, fun, arg=[], timeout=5, expr_form='glob')
The LocalClient object only works running as root on the salt-master, it is the
same interface used by the salt command line tool. The arguments are as
follows.
.. cmdoption:: tgt
The tgt option is the target specification, by default a target is passed
in as a bash shell glob. The expr_form option allows the tgt to be passed
as either a pcre regular expresion or as a python list.
.. cmdoption:: fun
The name of the function to call on the specified minions. The
documentation for these functions can be seen by running on the
salt-master: salt '*' sys.doc
.. cmdoption:: arg
The optional arg paramater is used to pass a list of options on to the
remote function
.. cmdoption:: timeout
The number of seconds to wait after the last minion returns but before all
minions return.
.. cmdoption:: expr_form
The type of tgt that is passed in, the allowed values are:
* 'glob' - Bash glob completion - Default
* 'pcre' - Perl style regular expresion
* 'list' - Python list of hosts

5
doc/ref/renderers.rst Normal file
View file

@ -0,0 +1,5 @@
=========
Renderers
=========
A python module that impments a render() method.

15
doc/ref/returners/index.rst Normal file
View file

@ -0,0 +1,15 @@
=========
Returners
=========
Salt returners allow the return data to be sent to arbitrary locations instead
of the salt master.
Full list of builtin returners
==============================
.. toctree::
:maxdepth: 1
:glob:
*

13
doc/ref/returners/returners.rst Normal file
View file

@ -0,0 +1,13 @@
===========================
:mod:`salt.returners.local`
===========================
.. automodule:: salt.returners.local
:members:
===========================
:mod:`salt.returners.redis`
===========================
.. automodule:: salt.returners.redis
:members:

6
doc/ref/states.rst Normal file
View file

@ -0,0 +1,6 @@
=================
State enforcement
=================
Enforce that specified packages are installed or that specified services are
running.

29
doc/topics/community.rst Normal file
View file

@ -0,0 +1,29 @@
=========
Community
=========
If you want to help develop Salt there is a great need and your patches are
welcome!
To assist in Salt development, you can help in a number of ways.
Posting patches to the mailing list
===================================
If you have a patch for Salt, please format it via :command:`git format-patch` and
send it to the Salt users mailing list. This allows the patch to give you the
contributor the credit for your patch, and gives the Salt community an archive
of the patch and a place for discussion.
Setting a Github pull request
=============================
This is probably the preferred method for contributions, simply create a Github
fork, commit your changes to the fork, and then open up a pull request.
Conclusion
==========
The goal here it to make contributions clear, make sure there is a trail for
where the code has come from, but most importantly, to give credit where credit
is due!

81
doc/topics/index.rst Normal file
View file

@ -0,0 +1,81 @@
====================
Introduction to Salt
====================
.. rubric:: We’re not just talking about NaCl.
Distributed remote execution
============================
Salt is a distributed remote execution system used to execute commands and
query data. 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 via its ability to handle larger loads of
information, and not just dozens, but hundreds or even thousands of individual
servers, handle them quickly and through a simple and manageable interface.
Simplicity
==========
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 disparate datacenters. 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.
Parallel execution
==================
The core function of Salt is to enable remote commands to be called in parallel
rather than in serial, to use a secure and encrypted protocol, the smallest and
fastest network payloads possible, and with a simple programmer interface. Salt
also introduces more granular controls to the realm of remote execution,
allowing for commands to be executed in parallel and for systems to be targeted
based on more than just hostname, but by system properties.
Building on proven technology
=============================
Salt takes advantage of a number of technologies and techniques. The networking
layer is built with the excellent `ZeroMQ`_ networking library, so Salt itself
contains a viable, and transparent, AMQ broker inside the daemon. Salt uses
public keys for authentication with the master daemon, then uses faster AES
encryption for payload communication, this means that authentication and
encryption are also built into Salt. Salt takes advantage of communication via
Python pickles, enabling fast and light network traffic.
.. _`ZeroMQ`: http://www.zeromq.org/
Python client interface
=======================
In order to allow for simple expansion, Salt execution routines can be written
as plain Python modules and 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.
Fast, flexible, scalable
========================
The result is a system that can execute commands across groups of varying size,
from very few to very many servers at considerably high speed. A system that is
very fast, easy to set up and amazingly malleable, able to suit the needs of
any number of servers working within the same system. Salt’s unique
architecture brings together the best of the remote execution world, amplifies
its capabilities and expands its range, resulting in this system that is as
versatile as it is practical, able to suit any network.
Open
====
Salt is developed under the `Apache 2.0 licence`_, 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. So, please feel free to
sprinkle some of this around your systems and let the deliciousness come forth.
.. _`Apache 2.0 licence`: http://www.apache.org/licenses/LICENSE-2.0.html

62
doc/topics/releases/0.6.0.rst Normal file
View file

@ -0,0 +1,62 @@
========================
Salt 0.6.0 release notes
========================
The Salt remote execution manager has reached initial functionality! Salt is a
management application which can be used to execute commands on remote sets of
servers.
The whole idea behind Salt is to create a system where a group of servers can
be remotely controlled from a single master, not only can commands be executed
on remote systems, but salt can also be used to gather information about your
server environment.
Unlike similar systems, like Func and MCollective, Salt is extremely simple to
setup and use, the entire application is contained in a single package, and the
master and minion daemons require no running dependencies in the way that Func
requires Certmaster and MCollective requires activeMQ.
Salt also manages authentication and encryption. Rather than using ssl for
encryption, salt manages encryption on a payload level, so the data sent across
the network is encrypted with fast aes encryption, and authentication uses RSA
keys. This means that Salt is fast, secure, and very efficient.
Messaging in Salt is executed with zeromq, so the message passing interface is
built into salt and does not require an external MQ server. This also adds
speed to Salt since there is no additional bloat on the networking layer, and
zeromq has already proven itself as a very fast networking system.
The remote execution in Salt is "Lazy Execution", in that once the command is
sent the requesting network connection is closed. This makes it easier to
detach the execution from the calling process on the master, it also means that
replies are cached, so that information gathered from historic commands can be
queried in the future.
Salt also allows users to make execution modules in python. Writers of these
modules should also be pleased to know that they have access to the impressive
information gathered from PuppetLabs' Facter application, making Salt module
more flexible. In the future I hope to also allow Salt to group servers based
on facter information as well.
All in all Salt is fast, efficient and clean, can be used from a simple command
line client or through an api, uses message queue technology to make network
execution extremely fast, and encryption is handled in a very fast and
efficient manner. Salt is also VERY easy to use and VERY easy to extend.
You can find the source code for Salt on my github page, I have also set up a
few wiki pages explaining how to use and set up Salt. If you are using Arch
Linux there is a package available in the Arch Linux AUR.
Salt 0.6.0 Source: https://github.com/downloads/thatch45/salt/salt-0.6.0.tar.gz
Github page: https://github.com/thatch45/salt
Wiki: https://github.com/thatch45/salt/wiki
Arch Linux Package: https://aur.archlinux.org/packages.php?ID=47512
I am very open to contributions, for instance I need packages for more Linux
distributions as well as BSD packages and testers.
Give Salt a try, this is the initial release and is not a 1.0 quality release,
but it has been working well for me! I am eager to get your feedback!

62
doc/topics/releases/0.7.0.rst Normal file
View file

@ -0,0 +1,62 @@
========================
Salt 0.7.0 release notes
========================
I am pleased to announce the release of Salt 0.7.0!
This release marks what is the first stable release of salt, 0.7.0 should be
suitable for general use.
0.7.0 Brings the following new features to Salt:
- Integration with facter data from puppet labs
- Allow for matching minions from the salt client via facter information
- Minion job threading, many jobs can be executed from the master at once
- Preview of master clustering support - Still experimental
- Introduce new minion modules for stats, virtualization, service management
and more
- Add extensive logging to the master and minion daemons
- Add sys.reload_functions for dynamic function reloading
- Greatly improve authentication
- Introduce the saltkey command for managing public keys
- Begin backend development preparatory to introducing butter
- Addition of man pages for the core commands
- Extended and cleaned configuration
0.7.0 Fixes the following major bugs:
- Fix crash in minions when matching failed
- Fix configuration file lookups for the local client
- Repair communication bugs in encryption
- Numerous fixes in the minion modules
The next release of Salt should see the following features:
- Stabilize the cluster support
- Introduce a remote client for salt command tiers
- salt-ftp system for distributed file copies
- Initial support for "butter"
Coming up next is a higher level management framework for salt called
Butter. I want salt to stay as a simple and effective communication
framework, and allow for more complicated executions to be managed via
Butter.
Right now Butter is being developed to act as a cloud controller using salt
as the communication layer, but features like system monitoring and advanced
configuration control (a puppet manager) are also in the pipe.
Special thanks to Joseph Hall for the status and network modules, and thanks
to Matthias Teege for tracking down some configuration bugs!
Salt can be downloaded from the following locations;
Source Tarball:
https://github.com/downloads/thatch45/salt/salt-0.7.0.tar.gz
Arch Linux Package:
https://aur.archlinux.org/packages.php?ID=47512
Please enjoy the latest Salt release!

119
doc/topics/releases/0.8.0.rst Normal file
View file

@ -0,0 +1,119 @@
========================
Salt 0.8.0 release notes
========================
Salt 0.8.0 is ready for general consumption!
The source tarball is available on github for download:
https://github.com/downloads/thatch45/salt/salt-0.8.0.tar.gz
A lot of work has gone into salt since the last release just 2 weeks ago, and
salt has improved a great deal. A swath of new features are here along with
performance and threading improvements!
The main new features of salt 0.8.0 are:
Salt-cp
Cython minion modules
Dynamic returners
Faster return handling
Lowered required python version to 2.6
Advanced minion threading
Configurable minion modules
Salt-cp -
=======================
The salt-cp command introduces the ability to copy simple files via salt to
targeted servers. Using salt-cp is very simple, just call salt-cp with a target
specification, the source file(s) and where to copy the files on the minions.
For instance:
# salt-cp ‘*’ /etc/hosts /etc/hosts
Will copy the local /etc/hosts file to all of the minions.
Salt-cp is very young, in the future more advanced features will be added, and
the functionality will much more closely resemble the cp command.
Cython minion modules -
========================
Cython is an amazing tool used to compile python modules down to c. This is
arguably the fastest way to run python code, and since pyzmq requires cython,
adding support to salt for cython adds no new dependencies.
Cython minion modules allow minion modules to be written in cython and
therefore executed in compiled c. Simply write the salt module in cython and
use the file extension “.pyx” and the minion module will be compiled when
the minion is started. An example cython module is included in the main
distribution called cytest.pyx:
https://github.com/thatch45/salt/blob/master/salt/modules/cytest.pyx
Dynamic Returners -
========================
By default salt returns command data back to the salt master, but now salt can
return command data to any system. This is enabled via the new returners
modules feature for salt. The returners modules take the return data and sends
it to a specific module. The returner modules work like minion modules, so any
returner can be added to the minions.
This means that a custom data returner can be added to communicate the return
data so anything from MySQL, redis, mongodb and more!
There are 2 simple stock returners in the returners directory:
https://github.com/thatch45/salt/tree/master/salt/returners
The documentation on writing returners will be added to the wiki shortly, and
returners can be written in pure python, or in cython.
Configurable Minion Modules -
==============================
Minion modules may need to be configured, now the options passed to the minion
configuration file can be accessed inside of the minion modules via the __opt__
dict.
Information on how to use this simple addition has been added to the wiki:
https://github.com/thatch45/salt/wiki/Writing-Salt-Modules
The test module has an example of using the __opts__ dict, and how to set
default options:
https://github.com/thatch45/salt/blob/master/salt/modules/test.py
Advanced Minion Threading:
==============================
In 0.7.0 the minion would block after receiving a command from the master, now
the minion will spawn a thread or multiprocess. By default python threads are
used because for general use they have proved to be faster, but the minion can
now be configured to use the python multiprocessing module instead. Using
multiprocessing will cause executions that are cpu bound or would otherwise
exploit the negative aspects of the Python GIL to run faster and more reliably,
but simple calls will still be faster with python threading.
The configuration option can be found in the minion configuration file:
https://github.com/thatch45/salt/blob/master/conf/minion
Lowered Supported Python to 2.6 -
The requirement for python 2.7 has been removed to support python 2.6. I have
received requests to take the minimum python version back to 2.4, but
unfortunately this will not be possible, since the zeromq python bindings do
not support python 2.4.
Salt 0.8.0 is a very major update, it also changes the network protocol slightly
which makes communication with older salt daemons impossible, your master and
minions need to be upgraded together!
I could use some help bringing salt to the people! Right now I only have
packages for Arch Linux, Fedora 14 and Gentoo. We need packages for Debian and
people willing to help test on more platforms. We also need help writing more
minion modules and returner modules. If you want to contribute to salt please
hop on the mailing list and send in patches, make a fork on github and send in
pull requests! If you want to help but are not sure where you can, please email
me directly or post tot he mailing list!
I hope you enjoy salt, while it is not yet 1.0 salt is completely viable and
usable!
-Thomas S. Hatch

79
doc/topics/releases/0.8.7.rst Normal file
View file

@ -0,0 +1,79 @@
========================
Salt 0.8.7 release notes
========================
It has been a month since salt 0.8.0, and it has been a long month! But Salt is
still coming along strong. 0.8.7 has a lot of changes and a lot of updates.
This update makes Salt’s ZeroMQ back end better, strips facter from the
dependencies, and introduces interfaces to handle more capabilities.
Many of the major updates are in the background, but the changes should shine
through to the surface. A number of the new features are still a little thin,
but the back end to support expansion is in place.
I also recently gave a presentation to the Utah Python users group in Salt Lake
City, the slides from this presentation are available here:
https://github.com/downloads/thatch45/salt/Salt.pdf
The video from this presentation will be available shortly.
The major new features and changes in Salt 0.8.7 are:
* Revamp ZeroMQ topology on the master for better scalability
* State enforcement
* Dynamic state enforcement managers
* Extract the module loader into salt.loader
* Make Job ids more granular
* Replace facter functionality with the new salt grains interface
* Support for “virtual” salt modules
* Introduce the salt-call command
* Better debugging for minion modules
The new ZeroMQ topology allows for better scalability, this will be required by
the need to execute massive file transfers to multiple machines in parallel and
state management. The new ZeroMQ topology is available in the aforementioned
presentation.
0.8.7 introduces the capability to declare states, this is similar to the
capabilities of Puppet. States in salt are declared via state data structures.
This system is very young, but the core feature set is available. Salt states
work around rendering files which represent Salt high data. More on the Salt
state system will be documented in the near future.
The system for loading salt modules has been pulled out of the minion class to
be a standalone module, this has enabled more dynamic loading of Salt modules
and enables many of the updates in 0.8.7 –
https://github.com/thatch45/salt/blob/master/salt/loader.py
Salt Job ids are now microsecond precise, this was needed to repair a race
condition unveiled by the speed improvements in the new ZeroMQ topology.
The new grains interface replaces the functionality of Facter, the idea behind
grains differs from Facter in that the grains are only used for static system
data, dynamic data needs to be derived from a call to a salt module. This makes
grains much faster to use, since the grains data is generated when the minion
starts.
Virtual salt modules allows for a salt module to be presented as something
other than its module name. The idea here is that based on information from the
minion decisions about which module should be presented can be made. The best
example is the pacman module. The pacman module will only load on Arch Linux
minions, and will be called pkg. Similarly the yum module will be presented as
pkg when the minion starts on a Fedora/RedHat system.
The new salt-call command allows for minion modules to be executed from the
minion. This means that on the minion a salt module can be executed, this is a
great tool for testing Salt modules. The salt-call command can also be used to
view the grains data.
In previous releases when a minion module threw an exception very little data
was returned to the master. Now the stack trace from the failure is returned
making debugging of minion modules MUCH easier.
Salt is nearing the goal of 1.0, where the core feature set and capability is
complete!
Salt 0.8.7 can be downloaded from github here:
https://github.com/downloads/thatch45/salt/salt-0.8.7.tar.gz
-Thomas S Hatch

82
doc/topics/releases/0.8.8.rst Normal file
View file

@ -0,0 +1,82 @@
========================
Salt 0.8.8 release notes
========================
Salt 0.8.8 is here! This release adds a great deal of code and some serious new
features. The latest release can be downloaded here:
https://github.com/downloads/thatch45/salt/salt-0.8.8.tar.gz
Improved Documentation has been set up for salt using sphinx thanks to the
efforts of Seth House. This new documentation system will act as the back end
to the salt website which is still under heavy development. The new sphinx
documentation system has also been used to greatly clean up the salt manpages.
The salt 7 manpage in particular now contains extensive information which was
previously only in the wiki. The new documentation can be found at:
http://thatch45.github.com/salt-www/
We still have a lot to add, and when the domain is set up I will post another
announcement.
More additions have been made to the ZeroMQ setup, particularly in the realm
of file transfers. Salt 0.8.8 introduces a built in, stateless, encrypted file
server which allows salt minions to download files from the salt master using
the same encryption system used for all other salt communications. The main
motivation for the salt file server has been to facilitate the new salt state
system.
Much of the salt code has been cleaned up and a new cleaner logging system has
been introduced thanks to the efforts of Pedro Algarvio. These additions will
allow for much more flexible logging to be executed by salt, and fixed a great
deal of my poor spelling in the salt docstrings! Pedro Algarvio has also
cleaned up the api, making it easier to embed salt into another application.
The biggest addition to salt found in 0.8.8 is the new state system. The salt
module system has received a new front end which allows salt to be used as a
configuration management system. The configuration management system allows for
system configuration to be defined in data structures. The configuration
management system, or as it is called in salt, the “salt state system” supports
many of the features found in other configuration managers, but allows for
system states to be written in a far simpler format, executes at blazing speeds,
and operates via the salt minion matching system. The state system also operates
within the normal scope of salt, and requires no additional configuration to
use.
The salt state system can enforce the following states with many more to come:
Packages
Files
Services
Executing commands
Hosts
The system used to define the salt states is based on a data structure, the
data structure used to define the salt states has been made to be as easy to
use as possible. The data structure is defined by default using a yaml file
rendered via a jinja template. This means that the state definition language
supports all of the data structures that yaml supports, and all of the
programming constructs and logic that jinja supports. If the user does not
like yaml or jinja the states can be defined in yaml-mako, json-jinja, or
json-mako. The system used to render the states is completely dynamic, and any
rendering system can be added to the capabilities of Salt, this means that a
rendering system that renders xml data in a cheetah template, or whatever you
can imagine, can be easily added to the capabilities of salt.
The salt state system also supports isolated environments, as well as matching
code from several environments to a single salt minion.
The feature base for Salt has grown quite a bit since my last serious
documentation push. As we approach 0.9.0 the goals are becoming very clear, and
the documentation needs a lot of work. The main goals for 0.9.0 are to further
refine the state system, fix any bugs we find, get Salt running on as many
platforms as we can, and get the documentation filled out. There is a lot more
to come as Salt moves forward to encapsulate a much larger scope, while
maintaining supreme usability and simplicity.
If you would like a more complete overview of Salt please watch the Salt
presentation:
Flash Video:
http://blip.tv/thomas-s-hatch/salt-0-8-7-presentation-5180182
OGV Video Download:
http://blip.tv/file/get/Thatch45-Salt087Presentation416.ogv
Slides:
https://github.com/downloads/thatch45/salt/Salt.pdf
-Thomas S Hatch

9
doc/topics/releases/index.rst Normal file
View file

@ -0,0 +1,9 @@
======================================
Release notes and upgrade instructions
======================================
.. toctree::
:maxdepth: 1
:glob:
*

56
doc/topics/specs/salt_auth_proto.rst Normal file
View file

@ -0,0 +1,56 @@
============================
Salt Authentication Protocol
============================
The Salt Authentication Protocol (SAP) defines a viable mechanism to create an
authenticated, encrypted communication channel. The SAP is used to create a
general purpose secure comunication channel.
Editor: Thomas S Hatch <thatch45@gmail.com>
Licence
=======
Copyright (c) 2011 Thomas S Hatch
This Specification is free software; you can redistribute it and/or modify it
under the terms of the GNU General Public License as published by the Free
Software Foundation; either version 3 of the License, or (at your option) any
later version.
This Specification is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
details.
You should have received a copy of the GNU General Public License along with
this program; if not, see <http://www.gnu.org/licenses>.
Change Process
==============
This Specification is a free and open standard[2] and is governed by the Digital
Standards Organization's Consensus-Oriented Specification System (COSS)[3].
Language
========
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD",
"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be
interpreted as described in RFC 2119[1].
Goals
=====
The Salt Authentication Protocol (SAP) defines an authentication system and a
mechanism for sending transport layer encrypted messages.
The goals of SAP are to:
Define a mechanism for secure authentication which can be utilized by other
protocols
Define a message structure which can be managed for clear, pubkey and aes
encrypted messages
Architecture
============

97
doc/topics/specs/salt_auth_proto_abs.rst Normal file
View file

@ -0,0 +1,97 @@
==============================================
Abstract on Salt Authentication and Encryption
==============================================
The Salt authentication and entcryption system uses Public Key authentication
and AES encryption to faciliate both authentication and high speed encryption.
The core components of this system can be seperated into a few sections,
Message Formatting, PubKey Handshake, AES key management, and encryption.
Message Formatting
==================
All messages passed within Salt are formatted with a clear header and a "load".
The header is always clear, and specifies the encryption used by the load. The
load can be encrypted with the private key of the sending system, or with the
shared, rotating, AES key.
The message itself is abstracted as a python dict in this fashion:
.. code-block:: python
{'enc': 'aes',
'load': <encrypted python pickle>}
When this message is recieved the load can be decrypted using the shared AES
key. The 'enc' dict ket can also be "pub" for pubkey encryption, or "clear"
for passing messages in the clear.
PubKey Handshake
=================
RSA Public keys are generated on the Salt master and on the Salt minion. When
A salt minion establishes an initial connection to the salt master the minion
sends its public key in the clear to the salt master, allong with the id of
the minion, and the command to execute on the master, in this case "_auth":
.. code-block:: python
{'enc': 'clear',
'load':
{'cmd': '_auth',
'id': <minion id>,
'pub': <minion public key>}}
If this is the first time this minion has authenticated, then the salt master
returns a clear message informing the minion that it is pending authentication.
The minion then queries the master every ten seconds awaiting authentication.
When the public key of the minion has been approved by the master, then the
master's public key is returned, with the AES key used to encrypt messages and
information on how to connect to the salt master publish interface.
The returned AES key is encrypted with the minion's public key, and can
therefore only be decrypted by the minion that sent out the public key.
Once the minion has authenticated and is in possesion of the revolving master
AES key (The AES key is regererated when the master restarts) then it atatches
the minion subscriber to the master publisher.
All messages sent from the publisher are encypted using the revolving AES key,
in the event that the master restarts the minions will all have an invalid
AES key because it has been regenerated on the master. The master will then
send out a publication that the minions cannot decrypt. If the minion recieves
a publication that cannot be decrypted then the minion will re-authenticate,
obtain the correct AES key, and decrypt the message. This means that the
AES key on the salt master can safely revolve without inturupting the minion
connection.
Regular Communication
=====================
Once the minion has authenticated, then all messages sent between the minion
and the master are encrypted using the revolving AES key and the {'enc': 'aes'}
header.
Source Files Implimenting Components
====================================
The pubkey authentication is managed via the salt.master module:
https://github.com/thatch45/salt/blob/master/salt/master.py
The regular minion authentication is managed via the salt.crypt module:
https://github.com/thatch45/salt/blob/master/salt/crypt.py
The salt.crypt module contains a class "SAuth" that can be used for
standalone authentication with the Salt master, this is most likely the best
place to start when looking into how the authentication mechanism works
The encrypted "load" portion of the messages are encrypted and decrypted using
the Crypticle class in the crypt module.
Conclusion
==========
In the end Salt uses formatted messages with clear header data to specify how
the message data is encrypted. Only uses pubkey encryption for authentication
and to securely retrive the master AES key. Then all regular communication
is sent in AES encrypted messages.

244
doc/topics/tutorial.rst Normal file
View file

@ -0,0 +1,244 @@
========
Tutorial
========
The Salt system setup is amazingly simple, as this is one of the central design
goals of Salt. Setting up Salt only requires that the Salt :term:`master` be
running and the Salt :term:`minions <minion>` point to the master.
.. glossary::
master
The Salt master is the central server that all minions connect to. You
run commands on the minions through the master and minions send data
back to the master (unless otherwise redirected with a :doc:`returner
<../ref/returners/index>`). It is started with the
:command:`salt-master` program.
minion
Salt minions are the potentially hundreds or thousands of servers that
you query and control from the master.
Installing Salt
===============
As of this writing packages for Salt only exist for Arch Linux, but rpms and
debs will be available in the future (contributions welcome).
.. contents:: Instructions by operating system
:depth: 1
:local:
Installing on Arch Linux
------------------------
The Arch Linux Salt package is available in the Arch Linux AUR (if you like
Salt vote for it on the Arch Linux AUR):
https://aur.archlinux.org/packages.php?ID=47512
For help using packages in the Arch Linux AUR:
https://wiki.archlinux.org/index.php/AUR
Installing on Debian or Ubuntu
------------------------------
Providing a .deb installer is on our short-list of things to do; until then
this is the best way to install Salt on Debian and Ubuntu systems:
1. Install the prerequisite packages::
aptitude install python-setuptools python-yaml python-crypto python-m2crypto cython libzmq-dev
.. note:: Installing on Ubuntu Lucid (10.04 LTS)
The ZeroMQ package is available starting with Maverick but it is not
yet available in Lucid backports. Fortunately, Chris Lea has made a
`ZeroMQ PPA`_ available. Install it before installing Salt::
aptitude install python-software-properties
add-apt-repository ppa:chris-lea/zeromq
aptitude update
aptitude install libzmq-dev
2. Grab the latest Python ZeroMQ bindings::
easy_install pyzmq
3. Install Salt:
.. parsed-literal::
easy_install --install-layout=deb \https://github.com/downloads/thatch45/salt/salt-|version|.tar.gz
Please take note of the ``--install-layout=deb`` flag. This is important
for a functioning installation of Salt.
.. _`ZeroMQ PPA`: https://launchpad.net/~chris-lea/+archive/zeromq
Installing from the source tarball
----------------------------------
1. Download the latest source tarball from the GitHub downloads directory for
the Salt project: https://github.com/thatch45/salt/downloads
2. Untar the tarball and run the :file:`setup.py` as root:
.. parsed-literal::
tar xvf salt-|version|.tar.gz
cd salt-|version|
python2 setup.py install
Salt dependencies
`````````````````
This is a basic Python setup, nothing fancy. Salt does require a number of
dependencies though, all of which should be available in your distribution's
packages.
* `Python 2.6`_
* `pyzmq`_ - ZeroMQ Python bindings
* `M2Crypto`_ - Python OpenSSL wrapper
* `YAML`_ - Python YAML bindings
* `PyCrypto`_ - The Python cryptography toolkit
.. _`Python 2.6`: http://python.org/download/
.. _`pyzmq`: https://github.com/zeromq/pyzmq
.. _`M2Crypto`: http://chandlerproject.org/Projects/MeTooCrypto
.. _`YAML`: http://pyyaml.org/
.. _`PyCrypto`: http://www.dlitz.net/software/pycrypto/
Optional Dependencies:
* gcc - dynamic `Cython`_ module compiling
.. _`Cython`: http://cython.org/
Configuring Salt
================
Salt configuration is very simple. The default configuration for the
:term:`master` will work for most installations and the only requirement for
setting up a :term:`minion` is to set the location of the master in the minion
configuration file. The configuration files will be installed to
:file:`/etc/salt` and are named after the respective components,
:file:`/etc/salt/master` and :file:`/etc/salt/minion`.
To make a minion check into the correct master simply edit the
:conf_minion:`master` variable in the minion configuration file to reference
the master DNS name or IPv4 address.
.. seealso::
For further information consult the :doc:`configuration guide
<../ref/configuration/index>`.
Running Salt
============
1. Start the :term:`master` in the foreground (to daemonize the process, pass
the :option:`-d flag <salt-master -d>`)::
salt-master
2. Start the :term:`minion` in the foreground (to daemonize the process, pass
the :option:`-d flag <salt-minion -d>`)::
salt-minion
.. seealso:: :doc:`salt-master manpage <../ref/cli/salt-master>` and
:doc:`salt-minion manpage <../ref/cli/salt-minion>`
Arch Linux init scripts
-----------------------
.. code-block:: bash
/etc/rc.d/salt-master start
/etc/rc.d/salt-minion start
Manage Salt public keys
=======================
Salt manages authentication with RSA public keys. The keys are managed on the
:term:`master` via the :command:`salt-key` command. Once a :term:`minion`
checks into the master the master will save a copy of the minion key. Before
the master can send commands to the minion the key needs to be "accepted".
1. List the accepted and unaccepted salt keys::
salt-key -L
2. Accept a minion key::
salt-key -a <minion id>
or accept all unaccepted minion keys::
salt-key -A
.. seealso:: :doc:`salt-key manpage <../ref/cli/salt-key>`
Order your minions around
=========================
Now that you have a :term:`master` and at least one :term:`minion`
communicating with each other you can perform commands on the minion via the
:command:`salt` command. Salt calls are comprised of three main components::
salt '<target>' <function> [arguments]
.. seealso:: :doc:`salt manpage <../ref/cli/salt>`
target
------
The target component allows you to filter which minions should run the
following function. The default filter is a glob on the minion id. E.g.::
salt '*' test.ping
salt '*.example.org' test.ping
Targets can be based on minion system information using the grains system::
salt -G 'os:Ubuntu' test.ping
.. seealso:: :doc:`Grains system <../ref/grains>`
Targets can be filtered by regular expression::
salt -E 'virtmach[0-9]' test.ping
Finally, targets can be explicitly specified in a list::
salt -L foo,bar,baz,quo test.ping
function
--------
A function is some functionality provided by a module. Salt ships with a large
collection of available functions. List all available functions on your
minions::
salt '*' sys.doc
Here are some examples:
Show all currently available minions::
salt '*' test.ping
Run an arbitrary shell command::
salt '*' cmd.run 'uname -a'
.. seealso:: :doc:`the full list of modules <../ref/modules/index>`
arguments
---------
Space-delimited arguments to the function::
salt '*' cmd.exec_code python 'import sys; print sys.version'

2
salt/__init__.py
View file

@ -71,7 +71,6 @@ class Master(object):
for name, level in self.opts['log_granular_levels'].iteritems():
salt.log.set_logger_level(name, level)
import logging
self.opts['logger'] = logging.getLogger('salt.stop-using-me')
verify_env([os.path.join(self.opts['pki_dir'], 'minions'),
os.path.join(self.opts['pki_dir'], 'minions_pre'),
os.path.join(self.opts['cachedir'], 'jobs'),
@ -139,7 +138,6 @@ class Minion(object):
salt.log.set_logger_level(name, level)
import logging
self.opts['logger'] = logging.getLogger('salt.stop-using-me')
verify_env([self.opts['pki_dir'], self.opts['cachedir']])
if self.cli['daemon']:

6
salt/config.py
View file

@ -70,12 +70,16 @@ def master_config(path):
'keep_jobs': 24,
'pki_dir': '/etc/salt/pki',
'cachedir': '/var/cache/salt',
'file_root': '/srv/salt',
'file_roots': {
'base': ['/srv/salt'],
},
'file_buffer_size': 1048576,
'hash_type': 'md5',
'conf_file': path,
'open_mode': False,
'auto_accept': False,
'renderer': 'yaml_jinja',
'state_top': 'top.yml',
'log_file': '/var/log/salt/master',
'log_level': 'warning',
'log_granular_levels': {},

51
salt/master.py
View file

@ -38,25 +38,26 @@ class Master(object):
'''
Clean out the old jobs
'''
if self.opts['keep_jobs'] == 0:
return
diff = self.opts['keep_jobs'] * 60 * 60
keep = int(time.time()) - diff
jid_root = os.path.join(self.opts['cachedir'], 'jobs')
for jid in os.listdir(jid_root):
if int(jid.split('.')[0]) < keep:
shutil.rmtree(os.path.join(jid_root, jid))
while True:
cur = datetime.datetime.strftime(
datetime.datetime.now(), '%Y%m%d%H'
)
if self.opts['keep_jobs'] == 0:
return
jid_root = os.path.join(self.opts['cachedir'], 'jobs')
for jid in os.listdir(jid_root):
if int(cur) - int(jid[:10]) > self.opts['keep_jobs']:
shutil.rmtree(os.path.join(jid_root, jid))
time.sleep(60)
def start(self):
'''
Turn on the master server components
'''
log.info('Starting the Salt Master')
multiprocessing.Process(target=self._clear_old_jobs).start()
reqserv = ReqServer(self.opts)
reqserv.run()
while True:
self._clear_old_jobs()
time.sleep(60)
class Publisher(multiprocessing.Process):
@ -329,28 +330,36 @@ class MWorker(multiprocessing.Process):
'''
Search the environment for the relative path
'''
fnd = {'path': '',
'rel': ''}
if not self.opts['file_roots'].has_key(env):
return False
return fnd
for root in self.opts['file_roots'][env]:
full = os.path.join(root, path)
if os.path.isfile(full):
return full
return False
fnd['path'] = full
fnd['rel'] = path
return fnd
return fnd
def _serve_file(self, load):
'''
Return a chunk from a file based on the data received
'''
ret = {'data': '',
'dest': ''}
if not load.has_key('path')\
or not load.has_key('loc')\
or not load.has_key('env'):
return False
path = self._find_file(load['path'], load['env'])
if not path:
return False
fn_ = open(path, 'rb')
return self.crypticle.dumps(ret)
fnd = self._find_file(load['path'], load['env'])
if not fnd['path']:
return self.crypticle.dumps(ret)
ret['dest'] = fnd['rel']
fn_ = open(fnd['path'], 'rb')
fn_.seek(load['loc'])
return self.crypticle.dumps(fn_.read(self.opts['file_buffer_size']))
ret['data'] = fn_.read(self.opts['file_buffer_size'])
return self.crypticle.dumps(ret)
def _file_hash(self, load):
'''
@ -361,7 +370,7 @@ class MWorker(multiprocessing.Process):
return False
path = self._find_file(load['path'], load['env'])
if not path:
return ''
return self.crypticle.dumps('')
ret = {}
ret['hsum'] = getattr(hashlib, self.opts['hash_type'])(
open(path, 'rb').read()).hexdigest()

64
salt/minion.py
View file

@ -282,7 +282,7 @@ class Matcher(object):
if item.has_key('match'):
matcher = item['match']
if hasattr(self, matcher + '_match'):
return getattr(self, matcher)
return getattr(self, matcher + '_match')
else:
log.error('Attempting to match with unknown matcher: %s', matcher)
return False
@ -350,36 +350,50 @@ class FileClient(object):
'''
Make sure that this path is intended for the salt master and trim it
'''
print path
if not path.startswith('salt://'):
raise MinionError('Unsupported path')
return path[:7]
return path[7:]
def get_file(self, path, dest, makedirs=False, env='base'):
def get_file(self, path, dest='', makedirs=False, env='base'):
'''
Get a single file from the salt-master
'''
path = self._check_proto(path)
payload = {'enc': 'aes'}
destdir = os.path.dirname(dest)
if not os.path.isdir(destdir):
if makedirs:
os.makedirs(destdir)
else:
return False
fn_ = open(dest, 'w+')
fn_ = None
if dest:
destdir = os.path.dirname(dest)
if not os.path.isdir(destdir):
if makedirs:
os.makedirs(destdir)
else:
return False
fn_ = open(dest, 'w+')
load = {'path': path,
'env': env,
'cmd': '_serve_file'}
while True:
load['loc'] = fn_.tell()
payload['load'] = self.crypticle.dumps(load)
if not fn_:
load['loc'] = 0
else:
load['loc'] = fn_.tell()
payload['load'] = self.auth.crypticle.dumps(load)
self.socket.send_pyobj(payload)
data = self.auth.crypticle.loads(self.socket.recv_pyobj())
if data == False:
return False
if not data:
if not data['data']:
break
fn_.write(data)
if not fn_:
dest = os.path.join(
self.opts['cachedir'],
'files',
data['dest']
)
destdir = os.path.dirname(dest)
if not os.path.isdir(destdir):
os.makedirs(destdir)
fn_ = open(dest, 'w+')
fn_.write(data['data'])
return dest
def cache_file(self, path, env='base'):
@ -387,8 +401,7 @@ class FileClient(object):
Pull a file down from the file server and store it in the minion file
cache
'''
dest = os.path.join(self.opts['cachedir'], 'files', path)
return self.get_file(path, dest, True, env)
return self.get_file(path, '', True, env)
def cache_files(self, paths, env='base'):
'''
@ -421,11 +434,14 @@ class FileClient(object):
return the location of the file
'''
if sls.count('.'):
root = sls.replace('.', '/')
for path in [root + '.sls', os.path.join(root, 'init.sls')]:
dest = self.cache_file(path, env)
if dest:
return dest
sls = sls.replace('.', '/')
for path in [
'salt://' + sls + '.sls',
os.path.join('salt://', sls, 'init.sls')
]:
dest = self.cache_file(path, env)
if dest:
return dest
return False
def master_opts(self):
@ -436,5 +452,5 @@ class FileClient(object):
load = {'cmd': '_master_opts'}
payload['load'] = self.auth.crypticle.dumps(load)
self.socket.send_pyobj(payload)
return self.auth.crypticle.loads(socket.recv_pyobj())
return self.auth.crypticle.loads(self.socket.recv_pyobj())

219
salt/modules/apt.py Normal file
View file

@ -0,0 +1,219 @@
'''
Support for apt
'''
import subprocess
def __virtual__():
'''
Confirm this module is on a Debian based system
'''
return 'pkg' if __grains__['os'] == 'Debian' else False
def available_version(name):
'''
The available version of the package in the repository
CLI Example:
salt '*' pkg.available_version <package name>
'''
version = ''
cmd = 'apt-cache show ' + name + ' | grep Version'
out = subprocess.Popen(cmd,
shell=True,
stdout=subprocess.PIPE).communicate()[0]
version_list = out.split()
if len(version_list) >= 2:
version = version_list[1]
return version
def version(name):
'''
Returns a string representing the package version or an empty string if not
installed
CLI Example:
salt '*' pkg.version <package name>
'''
pkgs = list_pkgs(name)
if pkgs.has_key(name):
return pkgs[name]
else:
return ''
def refresh_db():
'''
Updates the apt database to latest packages based upon repositories
Returns a dict: {'<database name>': Bool}
CLI Example:
salt '*' pkg.refresh_db
'''
cmd = 'apt-get update'
out = subprocess.Popen(cmd,
shell=True,
stdout=subprocess.PIPE).communicate()[0].split('\n')
servers = {}
for line in out:
cols = line.split()
if not len(cols):
continue
ident = " ".join(cols[1:4])
if cols[0].count('Get'):
servers[ident] = True
else:
servers[ident] = False
return servers
def install(pkg, refresh=False):
'''
Install the passed package
Return a dict containing the new package names and versions:
{'<package>': {'old': '<old-version>',
'new': '<new-version>']}
CLI Example:
salt '*' pkg.install <package name>
'''
if(refresh):
refresh_db()
ret_pkgs = {}
old_pkgs = list_pkgs()
cmd = 'apt-get -y install ' + pkg
subprocess.call(cmd, shell=True)
new_pkgs = list_pkgs()
for pkg in new_pkgs:
if old_pkgs.has_key(pkg):
if old_pkgs[pkg] == new_pkgs[pkg]:
continue
else:
ret_pkgs[pkg] = {'old': old_pkgs[pkg],
'new': new_pkgs[pkg]}
else:
ret_pkgs[pkg] = {'old': '',
'new': new_pkgs[pkg]}
return ret_pkgs
def remove(pkg):
'''
Remove a single package via apt-get remove
Return a list containing the names of the removed packages:
CLI Example:
salt '*' pkg.remove <package name>
'''
ret_pkgs = []
old_pkgs = list_pkgs()
cmd = 'apt-get -y remove ' + pkg
subprocess.call(cmd, shell=True)
new = list_pkgs()
for pkg in old_pkgs:
if not new_pkgs.has_key(pkg):
ret_pkgs.append(pkg)
return ret_pkgs
def purge(pkg):
'''
Remove a package via apt-get along with all configuration files and
unused dependencies as determined by apt-get autoremove
Returns a list containing the names of the removed packages
CLI Example:
salt '*' pkg.purge <package name>
'''
ret_pkgs = []
old_pkgs = list_pkgs()
# Remove inital package
purge_cmd = 'apt-get -y purge ' + pkg
subprocess.call(purge_cmd, shell=True)
# Remove any dependencies that are no longer needed
autoremove_cmd = 'apt-get -y autoremove'
subprocess.call(purge_cmd, shell=True)
new = list_pkgs()
for pkg in old_pkgs:
if not new_pkgs.has_key(pkg):
ret_pkgs.append(pkg)
return ret_pkgs
def upgrade(refresh=True):
'''
Upgrades all packages via apt-get dist-upgrade
Returns a list of dicts containing the package names, and the new and old versions:
[
{'<package>': {'old': '<old-version>',
'new': '<new-version>']
}',
...
]
CLI Example:
salt '*' pkg.upgrade
'''
if(update_repos):
refresh_db()
ret_pkgs = {}
old_pkgs = list_pkgs()
cmd = 'apt-get -y dist-upgrade'
subprocess.call(cmd, shell=True)
new_pkgs = list_pkgs()
for pkg in new_pkgs:
if old_pkgs.has_key(pkg):
if old_pkgs[pkg] == new_pkgs[pkg]:
continue
else:
ret_pkgs[pkg] = {'old': old_pkgs[pkg],
'new': new_pkgs[pkg]}
else:
ret_pkgs[pkg] = {'old': '',
'new': new_pkgs[pkg]}
return ret_pkgs
def list_pkgs(regex_string=""):
'''
List the packages currently installed in a dict:
{'<package_name>': '<version>'}
CLI Example:
salt '*' pkg.list_pkgs
'''
ret = {}
cmd = 'dpkg --list ' + regex_string
out = subprocess.Popen(cmd,
shell=True,
stdout=subprocess.PIPE).communicate()[0].split('\n')
for line in out:
cols = line.split()
if len(cols) and cols[0].count('ii'):
ret[cols[1]] = cols[2]
return ret

5
salt/modules/hosts.py
View file

@ -122,7 +122,10 @@ def rm_host(ip, alias):
if existing == alias:
continue
newline += '\t' + existing
lines[ind] = newline
if newline.strip() == ip:
lines[ind] = ''
else:
lines[ind] = newline
open(hfn, 'w+').writelines(lines)
return True

11
salt/modules/service.py
View file

@ -35,6 +35,17 @@ def stop(name):
name + ' stop')
return not subprocess.call(cmd, shell=True)
def restart(name):
'''
Restart the named service
CLI Example:
salt '*' service.restart <service name>
'''
cmd = os.path.join(grainmap[__grains__['os']],
name + ' restart')
return not subprocess.call(cmd, shell=True)
def status(name, sig=None):
'''
Return the status for a service, returns the PID or an empty string if the

9
salt/modules/state.py
View file

@ -50,3 +50,12 @@ def template_str(tem):
st_ = salt.state.State(__opts__)
return st_.call_template_str(tem)
def highstate():
'''
Retrive the state data from the salt master for this minion and execute it
CLI Example:
salt '*' state.highstate
'''
st_ = salt.state.HighState(__opts__)
return st_.call_highstate()

61
salt/state.py
View file

@ -278,17 +278,17 @@ class State(object):
return self.call_high(high)
return high
def HighState(object):
class HighState(object):
'''
Generate and execute the salt "High State". The High State is the compound
state derived from a group of template files stored on the salt master or
in a the local cache.
'''
def __init__(self, opts):
self.state = State(opts)
self.client = salt.minion.FileClient(opts)
self.matcher = salt.minion.Matcher(opts)
self.opts = self.__gen_opts(opts)
self.state = State(self.opts)
self.matcher = salt.minion.Matcher(self.opts)
def __gen_opts(self, opts):
'''
@ -306,17 +306,10 @@ def HighState(object):
opts['renderer'] = mopts['renderer']
if mopts['state_top'].startswith('salt://'):
opts['state_top'] = mopts['state_top']
elif mopts['state_top'].startswith(mopts['file_root']):
opts['state_top'] = os.path.join(
'salt://',
os.path.relpath(
mopts['state_top'], mopts['file_root'])
)
elif not mopts['state_top'].startswith('/'):
opts['state_top'] = os.path.join('salt://', mopts['state_top'])
elif mopts['state_top'].startswith('/'):
opts['state_top'] = os.path.join('salt://', mopts['state_top'][1:])
else:
log.error('Invalid top file location')
raise StateError('Invalid top file location')
opts['state_top'] = os.path.join('salt://', mopts['state_top'])
return opts
def get_top(self):
@ -326,7 +319,7 @@ def HighState(object):
top = self.client.cache_file(self.opts['state_top'], 'base')
return self.state.compile_template(top)
def top_matches(self):
def top_matches(self, top):
'''
Search through the top high data for matches and return the states that
this minion needs to execute.
@ -335,7 +328,6 @@ def HighState(object):
{'env': ['state1', 'state2', ...]}
'''
matches = {}
top = self.get_top()
for env, body in top.items():
for match, data in body.items():
if self.matcher.confirm_top(data):
@ -357,3 +349,42 @@ def HighState(object):
if state:
group.append(state)
return group
def render_state(self, sls, env, mods):
'''
Render a state file and retrive all of the include states
'''
fn_ = self.client.get_state(sls, env)
state = self.state.compile_template(fn_)
mods.add(sls)
if state:
if state.has_key('include'):
for sub_sls in state.pop('include'):
if not list(mods).count(sub_sls):
nstate, mods = self.render_state(sub_sls, env, mods)
if nstate:
state.update(nstate)
return state, mods
def render_highstate(self, matches):
'''
Gather the state files and render them into a single unified salt high
data structure.
'''
highstate = {}
for env, states in matches.items():
mods = set()
for sls in states:
state, mods = self.render_state(sls, env, mods)
if state:
highstate.update(state)
return highstate
def call_highstate(self):
'''
Run the sequence to execute the salt highstate for this minion
'''
top = self.get_top()
matches = self.top_matches(top)
high = self.render_highstate(matches)
return self.state.call_high(high)

2
salt/states/host.py
View file

@ -39,7 +39,7 @@ def absent(name, ip):
if __salt__['hosts.rm_host'](ip, name):
ret['changes'] = {'host': name}
ret['result'] = True
ret['comment'] = 'Removed host ' + host
ret['comment'] = 'Removed host ' + name
return ret
else:
ret['result'] = False

3
salt/states/pkg.py
View file

@ -27,8 +27,9 @@ def latest(name):
'''
Verify that the latest package is installed
'''
changes = {}
version = __salt__['pkg.version'](name)
avail = ['pkg.available_version'](name)
avail = __salt__['pkg.available_version'](name)
if avail > version:
changes = __salt__['pkg.install'](name, True)
if not changes:

2
setup.py
View file

@ -9,7 +9,7 @@ from distutils.extension import Extension
from distutils.sysconfig import get_python_lib, PREFIX
NAME = 'salt'
VER = '0.8.7'
VER = '0.8.8'
DESC = 'Portable, distrubuted, remote execution system'
mod_path = os.path.join(get_python_lib(), 'salt/modules/')