Merge remote-tracking branch 'white/master'

Conflicts:
	README
	doc/man/salt-cp.1
	doc/man/salt-key.1
	doc/man/salt-minion.1
	doc/man/salt.1
	doc/man/salt.7

README.rst

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

doc/man/salt-master.1

@@ -1,27 +0,0 @@
-.TH salt-master 1 "May 2011" "salt-master 0.8.7" "salt-master Manual"
-
-.SH NAME
-salt-master \- The salt master daemon, used to control the salt minions
-
-.SH SYNOPSIS
-.B salt-master [ options ]
-
-.SH DESCRIPTION
-The master daemon controls the salt minions
-
-.SH OPTIONS
-.TP
--h, --help
-Print a usage message briefly summarizing these command-line options.
-
-.TP
--d, --daemon
-Run the salt master as a daemon
-
-.TP
--c CONFIG, --config=CONFIG
-The master configuration file to use, the default is /etc/salt/master
-
-
-.SH AUTHORS
-Thomas S. Hatch <thatch@gmail.com>

doc/ref/cli/index.rst

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

doc/ref/cli/salt-call.rst

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

doc/ref/cli/salt-cp.rst

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

doc/ref/cli/salt-key.rst

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

doc/ref/cli/salt-master.rst

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

doc/ref/cli/salt-minion.rst

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

doc/ref/cli/salt.rst

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