Commit 0d2b8b7a authored by Joe Healy's avatar Joe Healy

Imported Upstream version 0.12.1

parents
=============
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
----------------------------
Aaron Bull Schaefer <aaron@elasticdog.com>
Aaron Toponce <aaron.toponce@gmail.com>
Antti Kaihola <akaihol+github@ambitone.com>
archme <archme.mail@gmail.com>
Brad Barden <brad@mifflinet.net>
Brian Wagner <wags@wagsworld.net>
Carlo Pires <carlopires@gmail.com>
Chris Scheller <schelcj@umich.edu>
Christer Edwards <christer.edwards@gmail.com>
Clint Savage <herlo1@gmail.com>
Corey Quinn <corey@sequestered.net>
David Boucha <boucha@gmail.com>
David Pravec <alekibango@pravec.tk>
Doug Renn <renn@nestegg.com>
Eivind Uggedal <eivind@uggedal.com>
epoelke@gmail.com <epoelke@heartflow.com>
Eric Poelke <epoelke@gmail.com>
Erik Nolte <enolte@beyondoblivion.com>
Evan Borgstrom <evan@fatbox.ca>
Jed Glazner <jglazner@coldcrow.com>
Jeff Bauer <jbauer@rubic.com>
Jeffrey C. Ollie <jeff@ocjtech.us>
Jeff Schroeder <jeffschroeder@computer.org>
Jonas Buckner <buckner.jonas@gmail.com>
Joseph Hall <perlhoser@gmail.com>
Josmar Dias <josmarnet@gmail.com>
Kent Tenney <ktenney@gmail.com>
Marc Abramowitz <marc+github@marc-abramowitz.com>
Markus Gattol <markus.gattol@sunoano.org>
Martin Schnabel <mb0@mb0.org>
Matthew Printz <hipokrit@gmail.com>
Matthias Teege <matthias-git@mteege.de>
Maxim Burgerhout <maxim@wzzrd.com>
Mitch Anderson <mitch@metauser.net>
Nathaniel Whiteinge <seth@eseth.com>
Nigel Owen <nigelowen2.gmail.com>
Pedro Algarvio <pedro@algarvio.me>
Pierre Carrier <pierre@spotify.com>
Rhys Elsmore <me@rhys.io>
Seth House <seth@eseth.com>
Seth Vidal <skvidal@fedoraproject.org>
Thomas Schreiber <tom@rizumu.us>
Thomas S Hatch <thatch45@gmail.com>
Tor Hveem <xt@bash.no>
Travis Cline <travis.cline@gmail.com>
Wieland Hoffmann <themineo+github@gmail.com>
Growing Community
--------------------------------
Salt is a rapidly growing project with a large community, to view all
contributors please check ohloh, this file can sometimes be out of date:
https://www.ohloh.net/p/salt/contributors
Developing Salt
===============
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.
Setting a Github pull request
-----------------------------
This is the preferred method for contributions, simply create a Github
fork, commit your changes to the fork, and then open up a pull request.
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.
Contributions Welcome!
----------------------
The goal here is 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!
The `Open Comparison Contributing Docs`__ explains the workflow for forking,
cloning, branching, committing, and sending a pull request for the git
repository.
``git pull upstream develop`` is a shorter way to update your local repository
to the latest version.
.. __: http://opencomparison.readthedocs.org/en/latest/contributing.html
Editing and Previewing the Docs
-------------------------------
You need ``sphinx-build`` to build the docs. In Debian/Ubuntu this is provided
in the ``python-sphinx`` package.
Then::
cd doc; make html
- The docs then are built in the ``docs/_build/html/`` folder. If you make
changes and want to see the results, ``make html`` again.
- The docs use ``reStructuredText`` for markup. See a live demo at
http://rst.ninjs.org/
- The help information on each module or state is culled from the python code
that runs for that piece. Find them in ``salt/modules/`` or ``salt/states/``
Installing Salt for development
-------------------------------
Clone the repository using::
git clone https://github.com/saltstack/salt
Create a new `virtualenv`_::
virtualenv /path/to/your/virtualenv
.. note:: site packages
If you wish to use installed packages rather than have pip download and
compile new ones into this environment, add "--system-site-packages".
.. _`virtualenv`: http://pypi.python.org/pypi/virtualenv
Activate the virtualenv::
source /path/to/your/virtualenv/bin/activate
Install Salt (and dependencies) into the virtualenv::
pip install -e ./salt # the path to the salt git clone from above
.. note:: Installing M2Crypto
You may need ``swig`` and ``libssl-dev`` to build M2Crypto. If you
encounter the error ``command 'swig' failed with exit status 1``
while installing M2Crypto, try installing it with the following command::
env SWIG_FEATURES="-cpperraswarn -includeall -D__`uname -m`__ -I/usr/include/openssl" pip install M2Crypto
Debian and Ubuntu systems have modified openssl libraries and mandate that
a patched version of M2Crypto be installed. This means that M2Crypto
needs to be installed via apt:
apt-get install python-m2crypto
Running a self-contained development version
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
During development it is easiest to be able to run the Salt master and minion
that are installed in the virtualenv you created above, and also to have all
the configuration, log, and cache files contained in the virtualenv as well.
Copy the master and minion config files into your virtualenv::
mkdir -p /path/to/your/virtualenv/etc/salt
cp ./salt/conf/master.template /path/to/your/virtualenv/etc/salt/master
cp ./salt/conf/minion.template /path/to/your/virtualenv/etc/salt/minion
Edit the master config file:
1. Uncomment and change the ``user: root`` value to your own user.
2. Uncomment and change the ``root_dir: /`` value to point to
``/path/to/your/virtualenv``.
3. If you are also running a non-development version of Salt you will have to
change the ``publish_port`` and ``ret_port`` values as well.
Edit the minion config file:
1. Repeat the edits you made in the master config for the ``user`` and
``root_dir`` values as well as any port changes.
2. Uncomment and change the ``master: salt`` value to point at ``localhost``.
3. Uncomment and change the ``id:`` value to something descriptive like
"saltdev". This isn't strictly necessary but it will serve as a reminder of
which Salt installation you are working with.
.. note:: Using `salt-call` with a :doc:`Standalone Minion </topics/tutorials/standalone_minion>`
If you plan to run `salt-call` with this self-contained development
environment in a masterless setup, you should invoke `salt-call` with
``-c /path/to/your/virtualenv/etc/salt`` so that salt can find the minion
config file. Without the ``-c`` option, Salt finds its config files in `/etc/salt`.
Start the master and minion, accept the minon's key, and verify your local Salt
installation is working::
salt-master -c ./etc/salt -d
salt-minion -c ./etc/salt -d
salt-key -c ./etc/salt -L
salt-key -c ./etc/salt -A
salt -c ./etc/salt '*' test.ping
File descriptor limit
~~~~~~~~~~~~~~~~~~~~~
Check your file descriptor limit with::
ulimit -n
If it is less than 2047, you should increase it with::
ulimit -n 2047
(or "limit descriptors 2047" for c-shell)
Running the tests
~~~~~~~~~~~~~~~~~
You will need a recent version of ``virtualenv``::
pip install "virtualenv>=1.8.2"
You will need ``mock`` to run the tests::
pip install mock
If you are on Python < 2.7 then you will also need unittest2::
pip install unittest2
Finally you use setup.py to run the tests with the following command::
./setup.py test
For greater control while running the tests, please try::
./tests/runtests.py -h
Salt - Remote execution system
Copyright 2011 Thomas S Hatch
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
Metadata-Version: 1.1
Name: salt
Version: 0.12.1
Summary: Portable, distributed, remote execution and configuration management system
Home-page: http://saltstack.org
Author: Thomas S Hatch
Author-email: thatch45@gmail.com
License: UNKNOWN
Description: UNKNOWN
Platform: UNKNOWN
Classifier: Programming Language :: Python
Classifier: Programming Language :: Cython
Classifier: Programming Language :: Python :: 2.6
Classifier: Programming Language :: Python :: 2.7
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: POSIX :: Linux
Classifier: Topic :: System :: Clustering
Classifier: Topic :: System :: Distributed Computing
=============
What is Salt?
=============
.. image:: https://secure.travis-ci.org/saltstack/salt.png?branch=develop
:target: http://travis-ci.org/saltstack/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. It handles them quickly and through a simple yet 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.
Granular Controls
=================
Salt also introduces powerful granular controls to the realm of remote execution.
By default, commands are executed in parallel. However, using more advanced
options, commands can be executed in batch groups or even in serial. By using
simple built-in filters or regular expression matching, systems can be targeted by
hostname, metadata or system properties such as number of cpus or OS type.
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. Salt itself
contains a viable, and transparent, ZeroMQ 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
the most excellent `msgpack`_ library, enabling fast and light network traffic.
.. _`ZeroMQ`: http://www.zeromq.org/
.. _`msgpack`: http://msgpack.org/
Python Client Interface
=======================
Salt execution routines can be written as plain Python modules and the data
collected from execution can be sent back to the master server, or any
arbitrary program. Salt can be called from a simple Python API, or from the
command line. This makes it easy to execute one-off commands as well as
operate as an integral part of a larger application.
Fast, Flexible, Scalable, Secure
================================
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. We consider speed to be a feature, not an afterthought. 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. Last but not least,
security is an intrinsic part of Salt and something not just
influencing how source code is written and how tests are done, but
also something that defines the overall architecture and has heavy
influence on the core design tenets.
Open
====