SALT(7)

NAME
salt - Salt Documentation Salt is a powerful remote execution manager that can be used to administer servers in a fast and efficient way.

Salt allows commands to be executed across large groups of servers. This means systems can be easily managed, but data can also be easily gathered. Quick introspection into running systems becomes a reality.

Remote execution is usually used to set up a certain state on a remote system. Salt addresses this problem as well, the salt state system uses salt state files to define the state a server needs to be in.

Between the remote execution system, and state management Salt addresses the backbone of cloud and data center management.

0.8.9 released!

Release announcement:

SALT 0.8.9 RELEASE NOTES

Salt 0.8.9 has finally arrived! Unfortunately this is much later than I had hoped to release 0.8.9, life has been very crazy over the last month. But despite challenges, Salt has moved forward!

This release, as expected, adds few new features and many refinements. One of the most exciting aspect of this release is that the development community for salt has grown a great deal and much of the code is from contributors.

Also, I have filled out the documentation a great deal. So information on States is properly documented, and much of the documentation that was out of date has been filled in.

  Download!

The Salt source can be downloaded from the salt github site:

https://github.com/downloads/thatch45/salt/salt-0.8.9.tar.gz

Or from PiPy:

http://pypi.python.org/packages/source/s/salt/salt-0.8.9.tar.gz

Here s the md5sum:

7d5aca4633bc22f59045f59e82f43b56

For instructions on how to set up Salt please see the tutorial

  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 master be running and the Salt minions point to the master.

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 returner). It is started with the 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).

  Instructions by operating system

•   Installing on Arch Linux

•   Installing on Debian or Ubuntu

•   Installing from the source tarball

  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:

    easy_install --install-layout=deb https://github.com/downloads/thatch45/salt/salt-0.9.0.tar.gz

    Please take note of the --install-layout=deb flag. This is important for a functioning installation of Salt.

  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 setup.py as root:

    tar xvf salt-0.9.0.tar.gz
    cd salt-0.9.0
    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

    Optional Dependencies:

•   gcc - dynamic Cython module compiling

  Configuring Salt

Salt configuration is very simple. The default configuration for the master will work for most installations and the only requirement for setting up a minion is to set the location of the master in the minion configuration file. The configuration files will be installed to /etc/salt and are named after the respective components, /etc/salt/master and /etc/salt/minion.

To make a minion check into the correct master simply edit the master variable in the minion configuration file to reference the master DNS name or IPv4 address.

See also

    For further information consult the configuration guide.

  Running Salt

1.  Start the master in the foreground (to daemonize the process, pass the -d flag):

    salt-master

2.  Start the minion in the foreground (to daemonize the process, pass the -d flag):

    salt-minion

See also

    salt-master manpage and salt-minion manpage

  Arch Linux init scripts

/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 master via the salt-key command. Once a 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

See also

    salt-key manpage

  Order your minions around

Now that you have a master and at least one minion communicating with each other you can perform commands on the minion via the salt command. Salt calls are comprised of three main components:

salt '<target>' <function> [arguments]

See also

    salt manpage

  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

See also

    Grains system

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'

See also

    the full list of modules

  arguments

Space-delimited arguments to the function:

salt '*' cmd.exec_code python 'import sys; print sys.version'

  New Features

  Salt Run

A big feature is the addition of Salt run, the salt-run command allows for master side execution modules to be made that gather specific information or execute custom routines from the master.

Documentation for salt-run can be found here:

http://saltstack.org/ref/runners.html

  Refined Outputters

One problem often complained about in salt was the fact that the output was so messy. Thanks to help from Jeff Schroeder a cleaner interface for the command output for the Salt cli has been made. This new interface makes adding new printout formats easy and additions to the capabilities of minion modules makes it possible to set the printout mode or outputter for functions in minion modules.

  Cross Calling Salt Modules

Salt modules can now call each other, the __salt__ dict has been added to the predefined references in minion modules. This new feature is documented in the modules documentation:

http://saltstack.org/ref/modules/index.html

  Watch Option Added to Salt State System

Now in Salt states you can set the watch option, this will allow watch enabled states to change based on a change in the other defined states. This is similar to subscribe and notify statements in puppet.

  Root Dir Option

Travis Cline has added the ability to define the option root_dir which allows the salt minion to operate in a subdir. This is a strong move in supporting the minion running as an unprivileged user

  Config Files Defined in Variables

Thanks again to Travis Cline, the master and minion configuration file locations can be defined in environment variables now.

  New Modules

Quite a few new modules, states, returners and runners have been made.

  New Minion Modules

  apt

Support for apt-get has been added, this adds greatly improved Debian and Ubuntu support to Salt!

  useradd and groupadd

Support for manipulating users and groups on Unix-like systems.

  moosefs

Initial support for reporting on aspects of the distributed file system, MooseFS. For more information on MooseFS please see: http://moosefs.org

Thanks to Joseph Hall for his work on MooseFS support.

  mount

Manage mounts and the fstab.

  puppet

Execute puppet on remote systems.

  shadow

Manipulate and manage the user password file.

  ssh

Interact with ssh keys.

  New States

  user and group

Support for managing users and groups in Salt States.

  mount

Enforce mounts and the fstab.

  New Returners

  mongo_return

Send the return information to a mongodb server.

  New Runners

  manage

Display minions that are up or down.

The latest Salt is 0.8.9:

https://github.com/downloads/thatch45/salt/salt-0.8.9.tar.gz

Additional packages can be downloaded from the download page:

DOWNLOAD SALT

Packages and dependencies for Salt can be downloaded here for specific operating systems. Please follow and specific instructions for your system.

  Salt From Source

The Salt source can be downloaded and installed directly from git:

# git clone git://github.com/thatch45/salt.git

The latest source tarball can be downloaded as well:

https://github.com/downloads/thatch45/salt/salt-0.8.9.tar.gz

Salt should run on any Unix like platform so long as the dependencies are met.

  Salt for Red Hat

Salt rpms have been prepared for Red Hat Enterprise Linux 6 and Fedora 15. While Fedora 15 only requires the Salt rpm Red Hat Enterprise Linux 6 requires that a newer version of ZeroMQ be installed than what is available in the EPEL repositories.

  Fedora rpms

Salt noarch rpm for Fedora 15:

https://github.com/downloads/thatch45/salt/salt-0.8.9-1.fc15.noarch.rpm

  Red Hat Enterprise Linux 6 rpms

The EPEL repository is required for Salt as well as updated ZeroMQ packages.

The Salt rpm can be downloaded here:

https://github.com/downloads/thatch45/salt/salt-0.8.9-1.el6.noarch.rpm

ZeroMQ backport:

https://github.com/downloads/thatch45/salt/zeromq-2.1.7-1.el6.x86_64.rpm

PyZMQ bindings backport:

https://github.com/downloads/thatch45/salt/python-zmq-2.1.7-1.el6.src.rpm

Package to set up EPEL repository (provided by the EPEL project):

http://download.fedoraproject.org/pub/epel/6/i386/epel-release-6-5.noarch.rpm

  Red Hat Enterprise Linux 5 rpms

Red Hat Enterprise Linux 5 requires more backports and the use of the python 2.6 stack provided in the EPEL repository. All of the listed packages need to be installed and the EPEL repository enabled to bring in the needed dependencies:

Salt rpm:

https://github.com/downloads/thatch45/salt/salt-0.8.9-1.el5.noarch.rpm

YAML bindings for python 2.6:

https://github.com/downloads/thatch45/salt/python26-PyYAML-3.08-4.el5.x86_64.rpm

ZeroMQ backport:

https://github.com/downloads/thatch45/salt/zeromq-2.1.7-1.el5.x86_64.rpm

PyZMQ bindings backport:

https://github.com/downloads/thatch45/salt/python26-zmq-2.1.7-1.el5.x86_64.rpm

  Salt for Arch Linux

Salt can be easily installed on Arch Linux, install the package from the Arch Linux AUR:

https://aur.archlinux.org/packages.php?ID=47512

Or install directly from git on Arch Linux:

https://aur.archlinux.org/packages.php?ID=47513

GETTING STARTED

A number of resources are available to get going with Salt.

If you want to get set up quickly and try out Salt, follow the tutorial.

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 master be running and the Salt minions point to the master.

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 returner). It is started with the 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).

  Instructions by operating system

•   Installing on Arch Linux

•   Installing on Debian or Ubuntu

•   Installing from the source tarball

  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:

    easy_install --install-layout=deb https://github.com/downloads/thatch45/salt/salt-0.9.0.tar.gz

    Please take note of the --install-layout=deb flag. This is important for a functioning installation of Salt.

  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 setup.py as root:

    tar xvf salt-0.9.0.tar.gz
    cd salt-0.9.0
    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

    Optional Dependencies:

•   gcc - dynamic Cython module compiling

  Configuring Salt

Salt configuration is very simple. The default configuration for the master will work for most installations and the only requirement for setting up a minion is to set the location of the master in the minion configuration file. The configuration files will be installed to /etc/salt and are named after the respective components, /etc/salt/master and /etc/salt/minion.

To make a minion check into the correct master simply edit the master variable in the minion configuration file to reference the master DNS name or IPv4 address.

See also

    For further information consult the configuration guide.

  Running Salt

1.  Start the master in the foreground (to daemonize the process, pass the -d flag):

    salt-master

2.  Start the minion in the foreground (to daemonize the process, pass the -d flag):

    salt-minion

See also

    salt-master manpage and salt-minion manpage

  Arch Linux init scripts

/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 master via the salt-key command. Once a 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

See also

    salt-key manpage

  Order your minions around

Now that you have a master and at least one minion communicating with each other you can perform commands on the minion via the salt command. Salt calls are comprised of three main components:

salt '<target>' <function> [arguments]

See also

    salt manpage

  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

See also

    Grains system

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'

See also

    the full list of modules

  arguments

Space-delimited arguments to the function:

salt '*' cmd.exec_code python 'import sys; print sys.version'

SALT IN DEPTH

While using and setting up Salt is a simple task, the capabilities of Salt run much deeper.

Gaining a better understanding of how Salt works will allow you to get much more out of Salt.

Presentation at SLLUG in May 2011 video | slides (PDF)

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 salt-master is configured via the master configuration file, and the salt-minion is configured via the minion configuration file.

  Configuration file examples

•   Example master configuration file

•   Example minion configuration file

  Example master configuration file

##### Primary configuration settings #####
##########################################
# The address of the interface to bind to
#interface: 0.0.0.0
# The port used by the publisher
#publish_port: 4505
# The number of worker threads to start, these threads are used to manage
# return calls made from minions to the master, if the master seems to be
# running slowly, increase the number of threads
#worker_threads: 5
# The port used by the communication interface
#ret_port: 4506
# The root directory prepended to these options: pki_dir, cachedir, log_file.
#root_dir: /
# Directory used to store public key data
#pki_dir: /etc/salt/pki
# Directory to store job and cache data
#cachedir: /var/cache/salt
# Set the number of hours to keep old job information
#keep_jobs: 24
# Set the directory used to hold unix sockets
#sock_dir: /tmp/salt-unix
#####        Security settings       #####
##########################################
# Enable "open mode", this mode still maintains encryption, but turns off
# authentication, this is only intended for highly secure environments or for
# the situation where your keys end up in a bad state. If you run in open more
# you do so at your own risk!
#open_mode: False
# Enable auto_accept, this setting will automatically accept all incoming
# public keys from the minions
#auto_accept: False
#####      State System settings     #####
##########################################
# 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
#state_top: top.yml
#
# The renderer to use on the minions to render the state data
#renderer: yaml_jinja
#####      File Server settings      #####
##########################################
# 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
#
# Default:
#file_roots:
#  base:
#    - /srv/salt
# 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.
#hash_type: md5
# The buffer size in the file server can be adjusted here:
#file_buffer_size: 1048576
#####          Syndic settings       #####
##########################################
# The Salt syndic is used to pass commands through a master from a higher
# master. Using the syndic is simple, if this is a master that will have
# syndic servers(s) below it set the "order_masters" setting to True, if this
# is a master that will be running a syndic daemon for passthrough the
# "syndic_master" setting needs to be set to the location of the master server
# to recieve commands from
#
# Set the order_masters setting to True if this master will command lower
# masters' syndic interfaces
#order_masters: False
#
# If this master will be running a salt syndic daemon, then the syndic needs
# to know where the master it is recieving commands from is, set it with the
# syndic_master value
#syndic_master: masterofmaster
#####      Peer Publish settings     #####
##########################################
# Salt minions can send commands to other minions, but only if the minion is
# allowed to. By default "Peer Publication" is disabled, and when enabled it
# is enabled for specific minions and specific commands. This allows secure
# compartmentalization of commands based on individual minions.
#
# The configuration uses regular expressions to match minions and then a list
# of regular expressions to match functions, the following will allow the
# minion authenticated as foo.example.com to execute functions from the test
# and pkg modules
# peer:
#   foo.example.com:
#       - test.*
#       - pkg.*
#
# This will allow all minions to execute all commands:
# peer:
#   .*:
#       - .*
# This is not recomanded, since it would allow anyone who gets root on any
# single minion to instantly have root on all of the minions!
#
#####         Cluster settings       #####
##########################################
# Salt supports automatic clustering, salt creates a single ip address which
# is shared among the individual salt components using ucarp. The private key
# and all of the minion keys are maintained across the defined cluster masters
# The failover service is automatically managed via these settings
# List the identifiers for the other cluster masters in this manner:
# [saltmaster-01.foo.com,saltmaster-02.foo.com,saltmaster-03.foo.com]
# The members of this master array must be running as salt minions to
# facilitate the distribution of cluster information
#cluster_masters: []
# The cluster modes are "paranoid" and "full"
# paranoid will only distribute the accepted minion public keys.
# full will also distribute the master private key.
#cluster_mode: paranoid
#####         Logging settings       #####
##########################################
# The location of the master log file
#log_file: /var/log/salt/master
# The level of messages to send to the log file.
# One of 'info', 'quiet', 'critical', 'error', 'debug', 'warning'.
# Default: 'warning'
#log_level: warning
#
# 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'
#   }
#
#log_granular_levels: {}

  Example minion configuration file

##### Primary configuration settings #####
##########################################
# Set the location of the salt master server, if the master server cannot be
# resolved, then the minion will fail to start
#master: salt
# Set the post used by the master reply and authentication server
#master_port: 4506
# The root directory prepended to these options: pki_dir, cachedir, log_file.
#root_dir: /
# The directory to store the pki information in
#pki_dir: /etc/salt/pki
# 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.
#id:
# Where cache data goes
#cachedir: /var/cache/salt
#####   Minion module management     #####
##########################################
# Disable specific modules, this will allow the admin to limit the level os
# access the master has to the minion
#disable_modules: [cmd,test]
#disable_returners: []
# Modules can be loaded from arbitrary paths, this enables the easy deployment
# of third party modules, modules for returners and minions can be loaded.
# Specify a list of extra directories to search for minion modules and
# returners. These paths must be fully qualified!
#module_dirs: []
#returner_dirs: []
#states_dirs: []
#render_dirs: []
# Enable Cython modules searching and loading. (Default: True)
#cython_enable: true
#####    State Management Settings    #####
###########################################
# The state management system executes all of the state templates on the minion
# to enable more granular control of system state management. The type of
# template and serialization used for state management needs to be configured
# on the minion, the default renderer is yaml_jinja. This is a yaml file
# rendered from a jinja template, the available options are:
# yaml_jinja
# yaml_mako
# json_jinja
# json_mako
#
#renderer: yaml_jinja
#
# Test allows for the state runs to only be test runs
#test: False
######        Security settings       #####
###########################################
# Enable "open mode", this mode still maintains encryption, but turns off
# authentication, this is only intended for highly secure environments or for
# the situation where your keys end up in a bad state. If you run in open mode
# you do so at your own risk!
#open_mode: False
######         Thread settings        #####
###########################################
# Disable multiprocessing support, by default when a minion receives a
# publication a new process is spawned and the command is executed therein.
#multiprocessing: True
######         Logging settings       #####
###########################################
# The location of the minion log file
#log_file: /var/log/salt/minion
# The level of messages to send to the log file.
# One of 'info', 'quiet', 'critical', 'error', 'debug', 'warning'.
# Default: 'warning'
#log_level: warning
#
# 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'
#   }
#
#log_granular_levels: {}
######      Module configuration      #####
###########################################
# Salt allows for modules to be passed arbitrary configuration data, any data
# passed here in valid yaml format will be passed on to the salt minion modules
# for use. It is STRONGLY recommended that a naming convention be used in which
# the module name is followed by a . and then the value. Also, all top level
# data must be allied via the yaml dict construct, some examples:
#
# A simple value for the test module:
#test.foo: foo
#
# A list for the test module:
#test.bar: [baz,quo]
#
# A dict for the test module:
#test.baz: {spam: sausage, cheese: bread}

See also

    example master configuration file | example minion configuration file

  Configuring the Salt Master

The configuration file for the salt-master is located at /etc/salt/master. The available options are as follows:

  Primary Master Configuration

  interface

Default: 0.0.0.0 (all interfaces)

The local interface to bind to.

interface: 192.168.0.1

  publish_port

Default: 4505

The network port to set up the publication interface

publish_port: 4505

  publish_pull_port

Default: 45055

The port used to communicate to the local publisher

publish_pull_port: 45055

  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.

worker_threads: 5

  worker_start_port

Default: 5

The port to begin binding workers on, the workers will be created on increasingly higher ports

worker_start_port: 45056

  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.

ret_port: 4506

  pki_dir

Default: /etc/salt/pki

The directory to store the pki authentication keys.

pki_dir: /etc/salt/pki

  cachedir

Default: /var/cache/salt

The location used to store cache information, particularly the job information for executed salt commands.

cachedir: /var/cache/salt

  keep_jobs

Default: 24

Set the number of hours to keep old job information

  Master Security Settings

  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 received 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.

open_mode: False

  auto_accept

Default: False

Enable auto_accept, this setting will automatically accept all incoming public keys from the minions

auto_accept: False

  Master State System Settings

  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

state_top: top.yml

  renderer

Default: yaml_jinja

The renderer to use on the minions to render the state data

renderer: yaml_jinja

  Master File Server Settings

  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

base:
  - /srv/salt

  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.

hash_type: md5

  file_buffer_size

Default: 1048576

The buffer size in the file server in bytes

file_buffer_size: 1048576

  Master Logging Settings

  log_file

Default: /etc/salt/pki

The location of the master log file

log_file: /var/log/salt/master

  log_level

Default: warning

The level of messages to send to the log file. One of 'info', 'quiet', 'critical', 'error', 'debug', 'warning'.

log_level: warning

  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

  master

Default: salt

The hostname or ipv4 of the master.

master: salt

  master_port

Default: 4506

The port of the master ret server, this needs to coincide with the ret_port option on the salt master.

master_port: 4506

  pki_dir

Default: /etc/salt/pki

The directory used to store the minion's public and private keys.

pki_dir: /etc/salt/pki

  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.

id: foo.bar.com

  cachedir

Default: /var/cache/salt

The location for minion cache data.

cachedir: /var/cache/salt

  Minion Module Management

  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.

disable_modules: [cmd,virt,test]

  open_mode

Default: False

Open mode can be used to clean out the pki key received from the salt master, turn on open mode, restart the minion, then turn off open mode and restart the minion to clean the keys.

open_mode: False

COMMAND LINE REFERENCE

  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

-h, --help
    Print a usage message briefly summarizing these command-line options

-t TIMEOUT, --timeout=TIMEOUT
    The timeout in seconds to wait for replies from the salt minions.

-E, --pcre
    The target expression will be interpreted as a pcre regular expression rather than a shell glob.

-L, --list
    The target expression will be interpreted as a comma delimited list, example: server1.foo.bar,server2.foo.bar,example7.quo.qux

-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.*'

-Q, --query
    Execute a salt command query, this can be used to find the results os a previous function call: -Q test.echo')

-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

salt(7) salt-master(1) salt-minion(1)

  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

-h, --help
    Print a usage message briefly summarizing these command-line options.

-d, --daemon
    Run the salt master as a daemon

-c CONFIG, --config=CONFIG
    The master configuration file to use, the default is /etc/salt/master

  salt-minion

The salt minion daemon, receives commands from a remote salt master.

  Synopsis

salt-minion [ options ]

  Description

The salt minion receives commands from the central salt master and replies with the results of said commands.

  Options

-h, --help
    Print a usage message briefly summarizing these command-line options.

-d, --daemon
    Run the salt minion as a daemon

-c CONFIG, --config=CONFIG
    The minion configuration file to use, the default is /etc/salt/minion

  salt-key

  Synopsis

salt-key [ options ]

  Description

Salt-key executes simple management of salt server public keys used for authentication.

  Options

-h, --help
    Print a usage message briefly summarizing these command-line options.

-l, --list
    List the unaccepted minion public keys.

-L, --list-all
    List all public keys on this salt master, both accepted and pending acceptance.

-a ACCEPT, --accept=ACCEPT
    Accept the named minion public key for command execution.

-A, --accept-all
    Accepts all pending public keys.

-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

  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

-h, --help
    Print a usage message briefly summarizing these command-line options

-t TIMEOUT, --timeout=TIMEOUT
    The timeout in seconds to wait for replies from the salt minions.

-E, --pcre
    The target expresion will be interpereted as a pcre regular expression rather than a shell glob.

-L, --list
    The target expression will be interpereted as a comma delimited list, example: server1.foo.bar,server2.foo.bar,example7.quo.qux

-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.*'

-Q, --query
    Execute a salt command query, this can be used to find the results os a previous function call: -Q test.echo')

-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

  salt-call

  Synopsis

salt-call [options]

  Options

-h, --help
    Print a usage message briefly summarizing these command-line options

-g, --grains
    Return the information generated by the salt grains

-m MODULE_DIRS, --module-dirs=MODULE_DIRS
    Specify an additional directories to pull modules from, multiple directories can be delimited by commas

-d, --doc
    Return the documentation for the specified module of for all modules if none are specified

    Salt can be controlled by a command line client by the root user on the Salt master. The Salt command line client uses the Salt client API to communicate with the Salt master server. The Salt client is straightforward and simple to use.

    Using the Salt client commands can be easily sent to the minions.

    Each of these commands accepts an explicit --config option to point to either the master or minion configuration file. If this option is not provided and the default configuration file does not exist then Salt falls back to use the environment variables SALT_MASTER_CONFIG and SALT_MINION_CONFIG.

See also

    ../configuration/index

  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:

salt '*foo.com' sys.doc

Salt can also define the target minions with regular expressions:

salt -E '.*' cmd.run 'ls -l | grep foo'

Or to explicitly list hosts, salt can take a list:

salt -L foo.bar.baz,quo.qux cmd.run 'ps aux | grep foo'

  More Powerful Targets

The simple target specifications, glob, regex and list will cover many use cases, and for some will cover all use cases, but more powerful options exist.

  Targeting with Grains

The Grains interface was built into Salt to allow minions to be targeted by system properties. So minions running on a particular operating system can be called to execute a function, or a specific kernel.

Calling via a grain is done by passing the -G option to salt, specifying a grain and a regular expression to match the value of the grain.

salt -G 'os:Fedora' test.ping

Will return True from all of the minions running Fedora.

To discover what grains are available and what the values are, execute the grains.item salt function:

salt '*' grains.items

  Targeting with Executions

As of 0.8.8 targeting with executions is still under heavy development and this documentation is written to refernce the behavior of execution matching in the future.

Execution matching allows for a primary function to be executed, and then based on the return of the primary function the main function is executed.

Execution matching allows for matching minions based on any arbitrairy running data on tne minions.

  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 sys.doc() function:

salt '*' sys.doc

  Compound Command Execution

If a series of commands need to be sent to a single target specification then the multiple commands can be send in a single publish. This can make gathering groups of information faster, and lowers the stress on the network for repeated commands.

Compound command execution works by sending a list of functions and arguments instead of sending a single function and argument. The functions are executed on the minion in the order they are defined on the command line, and then the data from all of the commands are returned in a dictionary. This means that the set of commands are called in a predictable way, and the returned data can be easily interpreted.

Executing compound commands if done by passing a comma delimited list of functions, followed by a comma delimited list of arguments:

salt '*' cmd.run,test.ping,test.echo 'cat /proc/cpuinfo',,foo

The trick to look out for here, is that if a function is being passed no arguments, then there needs to be a placeholder for the absent arguments. This is why in the above example, there are two commas right next to each other. test.ping takes no arguments, so we need to add another comma, otherwise Salt would attempt to pass "foo" to test.ping.

EXTENDING SALT

Writing your own customizations on top of Salt

  Introduction to Extending Salt

Salt is made to be used, and made to be extended. The primary goal of Salt is to provide a foundation which can be used to solve problems. And the goal of Salt is to not assume what those problems might be.

One of the greatest benefit of developing Salt has been the vast array of ways in which people have wanted to use it, while the original intention was as a communication layer for a cloud controller Salt has been extended to facilitate so much more.

  Client API

The primary interface used to extend salt, is to simply use it. Salt executions can be called via the Salt client api, making programming master side solutions with Salt is easy.

  Adding Loadable Plugins

Salt is comprised of a core platform that loads many types of easy to write plugins. The idea is to enable all of the breaking points in the salt processes to have a point of pluggable interaction. This means that all of the main features of Salt can be extended, modified or used.

The breaking points and helping interfaces span from convenience master side executions to manipulating the flow of how data is handled by Salt.

  Minion Execution Modules

The minion execution modules or just modules are the core to what salt is and does. These modules are found in:

https://github.com/thatch45/salt/tree/master/salt/modules

These modules are what is called by the salt command line and the salt client api. Adding modules is done by simply adding additional python modules to the modules directory and restarting the minion.

  Grains

Salt grains, or "grains of truth" are bits of static information that are generated when the minion starts. This information is useful when determining what package manager to default to, or where certain configuration files are stored on the minion.

The Salt grains are the interface used for auto detection and dynamic assignment of execution modules and types to specific salt minions.

The code used to generate the Salt grains can be found here:

https://github.com/thatch45/salt/tree/master/salt/grains

  States

Salt supports state enforcement, this makes Salt a high speed and very efficient solution for system configuration management.

States can be easily added to Salt by dropping a new state module in:

https://github.com/thatch45/salt/tree/master/salt/states

  Renderers

Salt states are controlled by simple data structures, these structures can be abstracted in a number of ways. While the default is to be in a yaml file wrapped in a jinja template, any abstraction can be used. This means that any format that can be dreamed is possible, so long as a renderer is written for it.

The existing renderers can be found here:

https://github.com/thatch45/salt/tree/master/salt/renderers

  Returners

The salt commands all produce a return value, that return value is sent to the salt master by default, but it can be sent anywhere. The returner interface makes it programmatically possible for the information to be sent to anything from an SQL or NOSQL database, to a custom application made to use Salt.

The existing returners can be found here:

https://github.com/thatch45/salt/tree/master/salt/returners

  Runners

Sometimes a certain application can be made to execute and run from the existing salt command line. This is where the salt runners come into play. The Salt Runners what is called by the salt-run command and are meant to act as a generic interface for encapsulating master side executions.

Existing Salt runners are located here:

https://github.com/thatch45/salt/tree/master/salt/runners

  Modules

Salt modules are the functions called by the salt command.

  Full list of builtin modules

  Contents

•   salt.modules.butterkvm

•   salt.modules.cluster

•   salt.modules.cmd

•   salt.modules.cp

•   salt.modules.disk

•   salt.modules.grains

•   salt.modules.network

•   salt.modules.pacman

•   salt.modules.service

•   salt.modules.state

•   salt.modules.status

•   salt.modules.sysctl

•   salt.modules.test

•   salt.modules.virt

•   salt.modules.yum

  salt.modules.butterkvm

Specialized routines used by the butter cloud component

salt.modules.butterkvm.create(instance, vda, image, pin)
    Create a virtual machine, this is part of the butter vm system and assumes that the files prepared by butter are available via shared storage. AKA - don't call this from the command line!

    Arguments: instance - string, The path to the instance directory for the given vm on shared storage vda - The location where the virtual machine image needs to be placed image - The image to move into place pin - a "pin" data structure defining the myriad of possible vdb-vbz disk images to generate.

    CLI Example: salt '*' butterkvm.create <instance dir> <root image location> <Destination> <pin data>

salt.modules.butterkvm.full_butter_data(local_path)
    Return the full virt info, but add butter data!

    CLI Example: salt '*' buttervm.full_butter_data <image_path>

salt.modules.butterkvm.libvirt_creds()
    Returns the user and group that the disk images should be owned by

    CLI Example: salt '*' butterkvm.libvirt_creds

salt.modules.butterkvm.local_images(local_path)
    return the virtual machine names for all of the images located in the butter cloud's local_path in a list:

    ['vm1.boo.com', 'vm2.foo.com']

    CLI Example: salt '*' buttervm.local_images <image_path>

  salt.modules.cluster

The cluster module is used to distribute and activate salt HA cluster components

salt.modules.cluster.distrib(minions, master_conf, master_pem, conf_file)
    Set up this minion as a failover master - only intended for use by the cluster interface

  salt.modules.cmd

A module for shelling out

Keep in mind that this module is insecure, in that it can give whomever has access to the master root execution access to all salt minions

salt.modules.cmd.exec_code(lang, code)
    Pass in two strings, the first naming the executable language, aka - python2, python3, ruby, perl, lua, etc. the second string containing the code you wish to execute. The stdout and stderr will be returned

    CLI Example: salt '*' cmd.exec_code ruby 'puts "cheese"'

salt.modules.cmd.has_exec(cmd)
    Returns true if the executable is available on the minion, false otherwise

    CLI Example: salt '*' cat

salt.modules.cmd.retcode(cmd, cwd='/home/thatch')
    Execute a shell command and return the command's return code.

    CLI Example: salt '*' cmd.retcode "file /bin/bash"

salt.modules.cmd.run(cmd, cwd='/home/thatch')
    Execute the passed command and return the output as a string

    CLI Example: salt '*' cmd.run "ls -l | grep foo | awk '{print $2}'"

salt.modules.cmd.run_all(cmd, cwd='/home/thatch')
    Execute the passed command and return a dict of return data

    CLI Example: salt '*' cmd.run_all "ls -l | grep foo | awk '{print $2}'"

salt.modules.cmd.run_stderr(cmd, cwd='/home/thatch')
    Execute a command and only return the standard error

    CLI Example: salt '*' cmd.run "ls -l | grep foo | awk '{print $2}'"

salt.modules.cmd.run_stdout(cmd, cwd='/home/thatch')
    Execute a command, and only return the standard out

    CLI Example: salt '*' cmd.run "ls -l | grep foo | awk '{print $2}'"

  salt.modules.cp

Minion side functions for salt-cp

salt.modules.cp.cache_file(path, env='base')
    Used to cache a single file in the local salt-master file cache.

salt.modules.cp.cache_files(paths, env='base')
    Used to gather many files from the master, the gathered files will be saved in the minion cachedir reflective to the paths retrieved from the master.

salt.modules.cp.get_file(path, dest, env='base')
    Used to get a single file from the salt master

salt.modules.cp.hash_file(path, env='base')
    Return the hash of a file, to get the hash of a file on the salt master file server prepend the path with salt://<file on server> otherwise, prepend the file with / for a local file.

    CLI Example:

salt.modules.cp.recv(files, dest)
    Used with salt-cp, pass the files dict, and the destination.

    This function receives small fast copy files from the master via salt-cp

  salt.modules.disk

Module for gathering disk information

salt.modules.disk.usage()
    Return usage information for volumes mounted on this minion

    CLI Example: salt '*' disk.usage

  salt.modules.grains

Control aspects of the grains data

salt.modules.grains.item(key)
    Return a singe component of the grains data

    CLI Example: salt '*' grains.item os

salt.modules.grains.items()
    Return the grains data

    CLI Example: salt '*' grains.items

  salt.modules.network

Module for gathering and managing network information

salt.modules.network.dig(host)
    Performs a DNS lookup with dig

    CLI Example: salt '*' network.dig archlinux.org

salt.modules.network.isportopen(host, port)
    Return status of a port

    CLI Example: salt '*' network.isportopen 127.0.0.1 22

salt.modules.network.netstat()
    Return information on open ports and states

    CLI Example: salt '*' network.netstat

salt.modules.network.ping(host)
    Performs a ping to a host

    CLI Example: salt '*' network.ping archlinux.org -c 4

salt.modules.network.traceroute(host)
    Performs a traceroute to a 3rd party host

    CLI Example: salt '*' network.traceroute archlinux.org

  salt.modules.pacman

A module to wrap pacman calls, since Arch is the best (https://wiki.archlinux.org/index.php/Arch_is_the_best)

salt.modules.pacman.available_version(name)
    The available version of the package in the repository

    CLI Example: salt '*' pkg.available_version <package name>

salt.modules.pacman.install(name, refresh=False)
    Install the passed package, add refresh=True to install with an -Sy

    Return a dict containing the new package names and versions: {'<package>': {'old': '<old-version>', 'new': '<new-version>']}

    CLI Example: salt '*' pkg.install <package name>

salt.modules.pacman.list_pkgs()
    List the packages currently installed in a dict: {'<package_name>': '<version>'}

    CLI Example: salt '*' pkg.list_pkgs

salt.modules.pacman.purge(name)
    Recursively remove a package and all dependencies which were installed with it, this will call a pacman -Rsc

    Return a list containing the removed packages:

    CLI Example: salt '*' pkg.purge <package name>

salt.modules.pacman.refresh_db()
    Just run a pacman -Sy, return a dict: {'<database name>': Bool}

    CLI Example: salt '*' pkg.refresh_db

salt.modules.pacman.remove(name)
    Remove a single package with pacman -R

    Return a list containing the removed packages:

    CLI Example: salt '*' pkg.remove <package name>

salt.modules.pacman.upgrade()
    Run a full system upgrade, a pacman -Syu

    Return a dict containing the new package names and versions: {'<package>': {'old': '<old-version>', 'new': '<new-version>']}

    CLI Example: salt '*' pkg.upgrade

salt.modules.pacman.version(name)
    Returns a version if the package is installed, else returns an empty string

    CLI Example: salt '*' pkg.version <package name>

  salt.modules.service

Top level package command wrapper, used to translate the os detected by the grains to the correct service manager

salt.modules.service.restart(name)
    Restart the named service

    CLI Example: salt '*' service.restart <service name>

salt.modules.service.start(name)
    Start the specified service

    CLI Example: salt '*' service.start <service name>

salt.modules.service.status(name, sig=None)
    Return the status for a service, returns the PID or an empty string if the service is running or not, pass a signature to use to find the service via ps

    CLI Example: salt '*' service.status <service name> [service signature]

salt.modules.service.stop(name)
    Stop the specified service

    CLI Example: salt '*' service.stop <service name>

  salt.modules.state

Control the state system on the minion

salt.modules.state.high(data)
    Execute the compound calls stored in a single set of high data This function is mostly intended for testing the state system

    CLI Example: salt '*' state.high '{"vim": {"pkg": ["installed"]}}'

salt.modules.state.highstate()
    Retrive the state data from the salt master for this minion and execute it

    CLI Example: salt '*' state.highstate

salt.modules.state.low(data)
    Execute a single low data call This function is mostly intended for testing the state system

    CLI Example: salt '*' state.low '{"state": "pkg", "fun": "installed", "name": "vim"}'

salt.modules.state.template(tem)
    Execute the information stored in a template file on the minion

    CLI Example: salt '*' state.template '<Path to template on the minion>'

salt.modules.state.template_str(tem)
    Execute the information stored in a template file on the minion

    CLI Example: salt '*' state.template_str '<Template String>'

  salt.modules.status

Module for returning various status data about a minion. These data can be useful for compiling into stats later.

salt.modules.status.all_status()
    Return a composite of all status data and info for this minoon. Warning: There is a LOT here!

    CLI Example: salt '*' status.all_status

salt.modules.status.cpuinfo()
    Return the CPU info for this minion

    CLI Example: salt '*' status.cpuinfo

salt.modules.status.cpustats()
    Return the CPU stats for this minon

    CLI Example: salt '*' status.cpustats

salt.modules.status.custom()
    Return a custom composite of status data and info for this minon, based on the minion config file. An example config like might be:

    status.cpustats.custom: [ 'cpu', 'ctxt', 'btime', 'processes' ]

    where we get our data, and custom is this function It is followed by a list of keys that we want returned.

    This function is meant to replace all_status(), which returns anything and everything, which we probably don't want.

    By default, nothing is returned. Warning: Depending on what you include, there can be a LOT here!

    CLI Example: salt '*' status.custom

salt.modules.status.diskstats()
    Return the disk stats for this minion

    CLI Example: salt '*' status.diskstats

salt.modules.status.diskusage(*args)
    Return the disk usage for this minion

    Usage: salt '*' status.diskusage [paths and/or filesystem types]

    CLI Example: salt '*' status.diskusage # usage for all filesystems salt '*' status.diskusage / /tmp # usage for / and /tmp salt '*' status.diskusage ext? # usage for ext2, ext3, & ext4 filesystems salt '*' status.diskusage / ext? # usage for / and all ext filesystems

salt.modules.status.loadavg()
    Return the load averages for this minion

    CLI Example: salt '*' status.loadavg

salt.modules.status.meminfo()
    Return the CPU stats for this minion

    CLI Example: salt '*' status.meminfo

salt.modules.status.netdev()
    Return the network device stats for this minion

    CLI Example: salt '*' status.netdev

salt.modules.status.netstats()
    Return the network stats for this minion

    CLI Example: salt '*' status.netstats

salt.modules.status.uptime()
    Return the uptime for this minion

    CLI Example: salt '*' status.uptime

salt.modules.status.vmstats()
    Return the virtual memory stats for this minion

    CLI Example: salt '*' status.vmstats

salt.modules.status.w()
    Return a list of logged in users for this minion, using the w command

    CLI Example: salt '*' status.w

  salt.modules.sysctl

Module for viewing and modifying sysctl parameters

salt.modules.sysctl.assign(name, value)
    Assign a single sysctl parameter for this minion

    CLI Example: salt '*' sysctl.assign net.ipv4.ip_forward 1

salt.modules.sysctl.get(name)
    Return a single sysctl parameter for this minion

    CLI Example: salt '*' sysctl.get net.ipv4.ip_forward

salt.modules.sysctl.show()
    Return a list of sysctl parameters for this minion

    CLI Example: salt '*' sysctl.show

  salt.modules.test

Module for running arbitrary tests

salt.modules.test.collatz(start)
    Execute the collatz conjecture from the passed starting number, returns the sequence and the time it took to compute. Used for performance tests.

    CLI Example: salt '*' test.collatz 3

salt.modules.test.conf_test()
    Return the value for test.foo in the minion configuration file, or return the default value

    CLI Example: salt '*' test.conf_test

salt.modules.test.cross_test(func, args=[])
    Execute a minion function via the __salt__ object in the test module, used to verify that the minion functions can be called via the __salt__module

    CLI Example: salt '*' test.cross_test file.gid_to_group 0

salt.modules.test.echo(text)
    Return a string - used for testing the connection

    CLI Example: salt '*' test.echo 'foo bar baz quo qux'

salt.modules.test.fib(num)
    Return a Fibonacci sequence up to the passed number, and the time it took to compute in seconds. Used for performance tests

    CLI Example: salt '*' test.fib 3

salt.modules.test.get_opts()
    Return the configuration options passed to this minion

    CLI Example: salt '*' test.get_opts

salt.modules.test.outputter(data)
    Test the outputter, pass in data to return

    CLI Example: salt '*' test.outputter foobar

salt.modules.test.ping()
    Just used to make sure the minion is up and responding Return True

    CLI Example: salt '*' test.ping

  salt.modules.virt

Work with virtual machines managed by libvirt

salt.modules.virt.create(vm_)
    Start a defined domain

    CLI Example: salt '*' virt.create <vm name>

salt.modules.virt.create_xml_path(path)
    Start a defined domain

    CLI Example: salt '*' virt.create_xml_path <path to xml file on the node>

salt.modules.virt.create_xml_str(xml)
    Start a domain based on the xml passed to the function

    CLI Example: salt '*' virt.create_xml_str <xml in string format>

salt.modules.virt.destroy(vm_)
    Hard power down the virtual machine, this is equivalent to pulling the power

    CLI Example: salt '*' virt.destroy <vm name>

salt.modules.virt.freecpu()
    Return an int representing the number of unallocated cpus on this hypervisor

    CLI Example: salt '*' virt.freemem

salt.modules.virt.freemem()
    Return an int representing the amount of memory that has not been given to virtual machines on this node

    CLI Example: salt '*' virt.freemem

salt.modules.virt.full_info()
    Return the node_info, vm_info and freemem

    CLI Example: salt '*' virt.full_info

salt.modules.virt.get_disks(vm_)
    Return the disks of a named vm

    CLI Example: salt '*' virt.get_disks <vm name>

salt.modules.virt.get_graphics(vm_)
    Returns the information on vnc for a given vm

    CLI Example: salt '*' virt.get_graphics <vm name>

salt.modules.virt.get_xml(vm_)
    Returns the xml for a given vm

    CLI Example: salt '*' virt.get_xml <vm name>

salt.modules.virt.is_kvm_hyper()
    Returns a bool whether or not this node is a hypervisor

    CLI Example: salt '*' virt.is_kvm_hyper

salt.modules.virt.list_vms()
    Return a list of virtual machine names on the minion

    CLI Example: salt '*' virt.list_vms

salt.modules.virt.migrate(vm_, target)
    Shared storage migration

    CLI Example: salt '*' virt.migrate <vm name> <target hypervisor>

salt.modules.virt.migrate_non_shared(vm_, target)
    Attempt to execute non-shared storage "all" migration

    CLI Example: salt '*' virt.migrate_non_shared <vm name> <target hypervisor>

salt.modules.virt.migrate_non_shared_inc(vm_, target)
    Attempt to execute non-shared storage "all" migration

    CLI Example: salt '*' virt.migrate_non_shared_inc <vm name> <target hypervisor>

salt.modules.virt.node_info()
    Return a dict with information about this node

    CLI Example: salt '*' virt.node_info

salt.modules.virt.pause(vm_)
    Pause the named vm

    CLI Example: salt '*' virt.pause <vm name>

salt.modules.virt.purge(vm_, dirs=False)
    Recursively destroy and delete a virtual machine, pass True for dir's to also delete the directories containing the virtual machine disk images - USE WITH EXTREAME CAUTION!

    CLI Example: salt '*' virt.purge <vm name>

salt.modules.virt.resume(vm_)
    Resume the named vm

    CLI Example: salt '*' virt.resume <vm name>

salt.modules.virt.seed_non_shared_migrate(disks, force=False)
    Non shared migration requires that the disks be present on the migration destination, pass the disks information via this function, to the migration destination before executing the migration.

    CLI Example: salt '*' virt.seed_non_shared_migrate <disks>

salt.modules.virt.shutdown(vm_)
    Send a soft shutdown signal to the named vm

    CLI Example: salt '*' virt.shutdown <vm name>

salt.modules.virt.undefine(vm_)
    Remove a defined vm, this does not purge the virtual machine image, and this only works if the vm is powered down

    CLI Example: salt '*' virt.undefine <vm name>

salt.modules.virt.virt_type()
    Returns the virtual machine type as a string

    CLI Example: salt '*' virt.virt_type

salt.modules.virt.vm_info()
    Return detailed information about the vms on this hyper in a dict:

{'cpu': <int>,
    'maxMem': <int>, 'mem': <int>, 'state': '<state>', 'cputime' <int>}

    CLI Example: salt '*' virt.vm_info

  salt.modules.yum

Support for YUM

salt.modules.yum.available_version(name)
    The available version of the package in the repository

    CLI Example: salt '*' pkg.available_version <package name>

salt.modules.yum.install(pkg, refresh=False)
    Install the passed package, add refresh=True to clean out the yum database before executing

    Return a dict containing the new package names and versions: {'<package>': {'old': '<old-version>', 'new': '<new-version>']}

    CLI Example: salt '*' pkg.install <package name>

salt.modules.yum.list_pkgs()
    List the packages currently installed in a dict: {'<package_name>': '<version>'}

    CLI Example: salt '*' pkg.list_pkgs

salt.modules.yum.purge(pkg)
    Yum does not have a purge, this function calls remove

    Return a list containing the removed packages:

    CLI Example: salt '*' pkg.purge <package name>

salt.modules.yum.refresh_db()
    Since yum refreshes the database automatically, this runs a yum clean, so that the next yum operation will have a clean database

    CLI Example: salt '*' pkg.refresh_db

salt.modules.yum.remove(pkg)
    Remove a single package with yum remove

    Return a list containing the removed packages:

    CLI Example: salt '*' pkg.remove <package name>

salt.modules.yum.upgrade()
    Run a full system upgrade, a yum upgrade

    Return a dict containing the new package names and versions: {'<package>': {'old': '<old-version>', 'new': '<new-version>']}

    CLI Example: salt '*' pkg.upgrade

salt.modules.yum.version(name)
    Returns a version if the package is installed, else returns an empty string

    CLI Example: salt '*' pkg.version <package name>

See also

    Full list of builtin modules

    Salt ships with many modules that cover a wide variety of tasks.

  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.

  Cross Calling Modules

All of the salt modules are available to each other, and can be "cross called". This means that when creating a module functions in modules which already exist can be called.

The variable __salt__ is packed into the modules after they are loaded into the salt minion. This variable is a python dictionary of all of the salt functions, laid out in the same way that they are made available to the salt command.

Salt modules can be cross called by accessing the value in the __salt__ dict:

def foo(bar):
    return __salt__['cmd.run'](bar)

This code will call the Salt cmd module's run function and pass the argument bar.

  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 grains.items() function:

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: 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. salt.modules.test, conf/minion.

  Printout Configuration

Since module functions can return different data, and the way the data is printed can greatly change the presentation, Salt has a printout configuration.

When writing a module the __outputter__ dict can be declared in the module. The __outputter__ dict contains a mapping of function name to Salt Outputter.

__outputter__ = {
                'run': 'txt'
                }

This will ensure that the text outputter is used.

  Virtual Modules

Sometimes a module should be presented in a generic way. A good example of this can be found in the package manager modules. The package manager changes from one operating system to another, but the salt module that interfaces with the package manager can be presented in a generic way.

The salt modules for package managers all contain a __virtual__ function which is called to define what systems the module should be loaded on.

The __virtual__ function is used to return either a string or False. If False is returned then the module is not loaded, if a string is returned then the module is loaded with the name of the string.

This means that the package manager modules can be presented as the pkg module regardless of what the actual module is named.

The package manager modules are the best example of using the __virtual__ function: https://github.com/thatch45/salt/blob/master/salt/modules/pacman.py https://github.com/thatch45/salt/blob/master/salt/modules/yum.py https://github.com/thatch45/salt/blob/master/salt/modules/apt.py

  Documentation

Salt modules are self documenting, the sys.doc() function will return the documentation for all available Facter modules:

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.

  Adding Documentation to Salt Modules

Since life is much better with documentation, it is strongly suggested that all Salt modules have documentation added. Any Salt modules submitted for inclusion in the main distribution of Salt will be required to have documentation.

Documenting Salt modules is easy! Just add a python docstring to the function.

def spam(eggs):
    '''
    A function to make some spam with eggs!
    CLI Example:
    salt '*' test.spam eggs
    '''
    return eggs

Now when the sys.doc call is executed the docstring will be cleanly returned to the calling terminal.

  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

def foo(bar):
    return bar
class baz:
    def __init__(self, quo):
        return quo

  Objects NOT Loaded into the Salt Minion

def _foobar(baz): # Preceded with an _
    return baz
cheese = {} # Not a callable python object

  Examples of Salt Modules

The existing Salt modules should be fairly easy to read and understand, the goal of the main distribution's Salt modules is not only to build a set of functions for salt, but to stand as examples for building out more Salt modules.

The existing modules can be found here: https://github.com/thatch45/salt/tree/master/salt/modules

The most simple module is the test module, it contains the simplest salt function, test.ping:

def ping():
    '''
    Just used to make sure the minion is up and responding
    Return True
    CLI Example:
    salt '*' test.ping
    '''
    return True

  Grains

Salt comes with an interface to derive information about the underlying system. This is called the grains interface, because it presents salt with grains of information.

The grains interface is made available to Salt modules and components so that the right salt minion commands are automatically available on the right systems.

It is important to remember that grains are bits of information loaded when the salt minion starts, so this information is static. This means that the information in grains is unchanging, therefore the nature of the data is static. So grains information are things like the running kernel, or the operating system.

  Writing Grains

Grains are easy to write, the grains interface is derived my executing all of the "public" functions found in the modules located in the grains package. The functions in the modules of the grains must return a python dict, the keys in the dict are the names of the grains, the values are the values.

This means that the actual grains interface is simply a python dict.

Before adding a grain to salt, consider what the grain is and remember that grains need to be static data.

  Examples of Grains

The core module in the grains package is where the main grains are loaded by the salt minion and the principal example of how to write grains:

https://github.com/thatch45/salt/blob/master/salt/grains/core.py

  Returners

  Full list of builtin returners

  Contents

•   salt.returners.local

•   salt.returners.redis

  salt.returners.local

The local returner is used to test the returner interface, it just prints the return data to the console to verify that it is being passed properly

salt.returners.local.returner(ret)
    Print the return data to the terminal to verify functionality

  salt.returners.redis

By default the return values of the commands sent to the salt minions are returned to the salt-master. But since the commands executed on the salt minions are detatched from the call on the salt master, there is no need for the minion to return the data to the salt master.

This is where the returner interface comes in. Returners are modules called in place of returning the data to the salt master.

The returner interface allows the return data to be sent to any system that can receive data. This means that return data can be sent to a Redis server, a MongoDB server, a MySQL server, or any system!

See also

    Full list of builtin returners

  Writing a Returner

A returner is a module which contains a returner function, the returner function must accept a single argument. this argument is the return data from the called minion function. So if the minion function test.ping is called the value of the argument will be True.

A simple returner is implimented here:

import redis
import json
def returner(ret):
    '''
    Return information to a redis server
    '''
    # Get a redis commection
    serv = redis.Redis(
                host='redis-serv.example.com',
                port=6379,
                db='0')
    serv.sadd("%(id)s:jobs" % ret, ret['jid'])
    serv.set("%(jid)s:%(id)s" % ret, json.dumps(ret['return']))
    serv.sadd('jobs', ret['jid'])
    serv.sadd(ret['jid'], ret['id'])

This simple example of a returner set to send the data to a redis server serializes the data as json and sets it in redis.

  Examples

The collection of builtin salt returners can be found here: https://github.com/thatch45/salt/tree/master/salt/returners

  State Enforcement

Salt offers an optional interface to manage the configuration or "state" of the salt minions. This interface is a fully capable mechanism used to enforce the state of systems from a central manager.

The Salt state system is made to be accurate, simple, and fast. And like the rest of the Salt system, Salt states are highly modular.

  Understanding the Salt State System Components

The Salt state system is comprised of a number of components, as a user, an understanding of the sls and renderer systems are needed. But as a developer, an understanding of salt states, as well as understanding salt states and how to write the states used by salt.

  Salt SLS System

The primary system used by the Salt state system is the SLS system. SLS stands for SaLt State.

The Salt States are files which contain the information about how to configure salt minions. The states are laid out in a directory tree and can be written in many different formats.

The contents of the files and they way they are laid out is intended to be as simple as possible while allowing for maximum flexibility. The files are laid out in states and contains information about how the minion needs to be configured.

  SLS File Layout

SLS files are laid out in the Salt file server. A simple layout can look like this:

top.sls
ssh.sls
sshd_config
users/init.sls
users/admin.sls
salt/init.sls
salt/master.sls

This example shows the core concepts of file layout. The top file is a key component and is used with salt matchers to match SLS states with minions. The .sls files are states. The rest of the files are seen by the salt master as just files that can be downloaded.

The states are translated into dot notation, so the ssh.sls file is seen as the ssh state, the users/admin.sls file is seen as the users.admin states.

The init.sls files are translated to be the state name of the parent directory, so the salt/init.sls file translates to the salt state.

The plain files are visible to the minions, as well as the state files, in salt, everything is a file, there is not "magic translation" of files and file types. This means that a state file can be distributed to minions just like a plain text or binary file.

  SLS Files

The Salt state files are simple sets of data. Since the SLS files are just data they can be represented in a number of different ways. The default format is yaml generated from a jinja template. This allows for the states files to have all the language constructs of Python, and the simplicity of yaml. State files can then be complicated jinja templates the translate down to yaml, or just plain and simple yaml files!

The State files are constructed data structures in a simple format. The format allows for many real activates to be expressed in very little text, while maintaining the utmost in readability and usability.

Here is an example of a Salt State:

vim:
    pkg:
        - installed
salt:
    pkg:
        - latest
    service:
        - running
        - require:
            - file: /etc/salt/minion
            - pkg: salt
        - names:
            - salt-master
            - salt-minion
        - watch:
            - file: /etc/salt/minion
/etc/salt/minion:
    file:
        - managed
        - source: salt://salt/minion
        - user: root
        - group: root
        - mode: 644
        - require:
            - pkg: salt

This short stanza will ensure that vim is installed, salt is installed and up to date, the salt-master and salt-minion daemons are running and the Salt minion configuration file is in place. It will also ensure everything is deployed in the right order and that the Salt services are restarted when the watched file updated.

  The Top File

The top file is the mapping for the state system. The top file specifies which minions should have which modules applied and which environments they should draw the states from.

The top file works by specifying the environment, containing matchers with lists of Salt states sent to the matching minions:

base:
    '*':
        - salt
        - users
        - users.admin
    'saltmaster.*':
        - match: pcre
        - salt.master

This simple example uses the base environment, which is built into the default salt setup, and then all minions will have the modules salt, users and users.admin since '*' will match all minions. Then the regular expression matcher will match all minions' with an id matching saltmaster.* and add the salt.master state.

  Renderer System

The Renderer system is a key component to the state system. SLS files are representations of Salt "high data" structures. All Salt cares about when reading an sls file is the data structure that is produced from file.

This allows Salt states to be represented by multiple types of files. The Renderer system can be used to allow different formats to be used for sls files.

The available renderers can be found in the renderers directory in the Salt source code:

https://github.com/thatch45/salt/tree/master/salt/renderers

By default sls files are rendered using jinja as a templating engine, and yaml as the serialization format. Since the rendering system can be extended simply by adding a new renderer to the renderers directory, it is possible that any structured file could be used to represent the SLS files.

In the future xml and raw python will be added, as well as many other formats.

  Salt Runners

Salt runners are convenience applications executed with the salt-run command.

A Salt runner can be a simple client call, or a complex application.

The use for a salt running is to build a frontend hook for running sets of commands via salt of creating special formatted output.

  Writing Salt Runners

Salt runners can be easily written, the work in a similar way to Salt modules except they run on the server side.

A runner is a python module that contains functions, each public function is a runner that can be executed via the salt-run command.

If a python module named test.py is created in the runners directory and contains a function called foo then the function could be called with:

# salt '*' test.foo

  Examples

The best examples of runners can be found in the Salt source:

https://github.com/thatch45/salt/blob/master/salt/runners

A simple runner that returns a well formated list of the minons that are responding to salt calls would look like this:

# Import salt modules
import salt.client
def up():
    '''
    Print a list of all of the minions that are up
    '''
    client = salt.client.LocalClient(__opts__['config'])
    minions = client.cmd('*', 'test.ping', timeout=1)
    for minion in sorted(minions):
        print minion

  Renderers

The Salt state system operates by gathering information from simple data structures. The state system was designed in this way to make interacting with it generic and simple. This also means that state files (sls files) can be one of many formats.

By default sls files are rendered as jinja templates and then parsed as yaml documents. But since the only thing the state system cares about is raw data, the sls files can be any structured format that can be dreamed up.

Currently there is support for jinja + yaml, mako + yaml, jinja + json and mako + json. But renderers can be written to support anything. This means that the Salt states could be managed by xml files, html files, puppet files, or any format that can be translated into the data structure used by the state system.

  Writing Renderers

Writing a renderer is easy, all that is required is that a python module is placed in the rendered directory and that the module implements the render function. The render function will be passed the path of the sls file. In the render function, parse the passed file and return the data structure derived from the file.

  Examples

The best place to find examples of renderers is in the Salt source code. The renderers included with Salt can be found here:

https://github.com/thatch45/salt/blob/master/salt/renderers

Here is a simple jinja + yaml example:

# Import python libs
import os
# Import Third Party libs
import yaml
from jinja2 import Template
def render(template):
    '''
    Render the data passing the functions and grains into the rendering system
    '''
    if not os.path.isfile(template):
        return {}
    passthrough = {}
    passthrough.update(__salt__)
    passthrough.update(__grains__)
    template = Template(open(template, 'r').read())
    yaml_data = template.render(**passthrough)
    return yaml.load(yaml_data)

  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:

# Import the salt client library
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:

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.

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 expression or as a python list.

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

arg The optional arg parameter is used to pass a list of options on to the remote function

timeout
    The number of seconds to wait after the last minion returns but before all minions return.

expr_form
    The type of tgt that is passed in, the allowed values are:

•   'glob' - Bash glob completion - Default

•   'pcre' - Perl style regular expression

•   'list' - Python list of hosts

  Compound Command Execution With the Salt API

The Salt client API can also send what is called a compound command. Often a collection of commands need to be executed on the targeted minions, rather than send the commands one after another, they can be send in a single publish containing a series of commands. This can dramatically lower overhead and speed up the application communicating with Salt.

When commands are executed with compound execution the minion functions called are executed in serial on the minion and the return value is sent back in a different fashion. The return value is a dict, with the function names as keys to the function returns as values.

Using the compound command execution system via the API requires that the fun value and the arg value are lists matching by index. This ensures that the order of the executions can be controlled. Any function that has no arguments MUST have an empty array in the corresponding arg index.

# Import the salt client library
import salt.client
# create a local client object
client = salt.client.LocalClient()
# make compound execution calls with the cmd method
ret = client.cmd('*', ['cmd.run', 'test.ping', 'test.echo'], [['ls -l'], [], ['foo']])

This will execute cmd.run ls -l then test.ping and finally test.echo foo. The return data from the minion will look like this:

{'cmd.run': '<output from ls -l>',
 'test.ping': True,
 'test.echo': 'foo'}

  Salt File Server

Salt comes with a simple file server suitable for distributing files to the salt minions. The file server is a stateless ZeroMQ server that is built into the salt master.

The main intent of the Salt File server is the present files for use in the Salt state system. With this said, the Salt file server can be used for any general file transfer from the master to the minions.

  The cp Module

The cp module is the home of minion side file server operations. The cp module is used by the Salt state system, salt-cp and can be used to distribute files presented by the Salt file server.

  Environments

Since the file server is made to work with the Salt state system, it supports environments. The environments are defined in the master config file and when referencing an environment the file specified will be based on the root directory of the environment.

  get_file

The cp.get_file function can be used on the minion to download a file from the master, the syntax looks like this:

# salt '*' cp.get_file salt://vimrc /etc/vimrc

This will instruct all salt minions to download the vimrc file and copy it to /etc/vimrc

  File Server Client API

A client API is available which allows for modules and applications to be written which make use of the Salt file server.

The file server uses the same authentication and encryption used by the rest of the Salt system for network communication.

  FileClient Class

The FileClient class is used to set up the communication from the minion to the master. When creating a FileClient object the minion configuration needs to be passed in. When using the FileClient from within a minion module the built in __opts__ data can be passed:

import salt.minion
def get_file(path, dest, env='base'):
'''
Used to get a single file from the salt master
CLI Example:
salt '*' cp.get_file salt://vimrc /etc/vimrc
'''
# Create the FileClient object
client = salt.minion.FileClient(__opts__)
# Call get_file
return client.get_file(path, dest, False, env)

Using the FileClient class outside of a minion module where the __opts__ data is not available, it needs to be generated:

import salt.minion
import salt.config
def get_file(path, dest, env='base'):
'''
Used to get a single file from the salt master
'''
# Get the configuration data
opts = salt.config.minion_config('/etc/salt/minion')
# Create the FileClient object
client = salt.minion.FileClient(opts)
# Call get_file
return client.get_file(path, dest, False, env)

•   Modules: Writing modules | full list of modules

•   Grains: Grains

•   Returners: Writing returners | full list of returners

•   State enforcement: States | Renderers

•   Python API: Python API

•   File Server: File Server

SALT NETWORK TOPOLOGY

Salt can be extended beyond a simple master commanding minions, for more information read up on the peer and syndic interfaces.

  Salt Syndic

The Salt Syndic interface is a powerful tool which allows for the construction of Salt command topologies. A basic Salt setup has a Salt Master commanding a group of Salt Minions. The Syndic interface is a special passthrough minion, it is run on a master and connects to another master, then the master that the Syndic minion is listening to can control the minions attatched to the master running the syndic.

The intent for supporting many layouts is not presented with the intent of supposing the use of any single topology, but to allow a more flexible method of controlling many systems.

  Configuring the Syndic

Since the Syndic only needs to be attatched to a higher level master the configuration is very simple. On a master that is running a syndic to connect to a higher level master the syndic_master option needs to be set in the master config file. The syndic_master option contains the hostname or ip address of the master server that can control the master that the syndic is running on.

The master that the syndic connects to sees the syndic as an ordinary minion, and treats it as such. the higher level master will need to accept the syndic's minion key like any other minion. This master will also need to set the order_masters value in the configuration to True. The order_masters option in the config on the higher level master is very important, to control a syndic extra information needs to be sent with the publications, the order_masters option makes sure that the extra data is sent out.

  Running the Syndic

The Syndic is a seperate daemon that needs to be started on the master that is controlled by a higher master. Starting the Syndic daemon is the same as starting the other Salt daemons.

# salt-syndic

  Peer Communication

Salt 0.9.0 introduced the capability for salt minions to publish commands. The intent of this feature is not for salt minions to act as independent brokers one with another, but to allow salt minions to pass commands to each other.

The peer interface allows a minion to call out publications on the salt master and receive the return data.

Since this presents a viable security risk by allowing minions access to the master publisher the capability is turned off by default. The minions can be allowed access to the master publisher on a per minion basis based on regular expressions. Minions with specific ids can be allowed access to certain salt modules and functions.

  Configuration

The configuration is done under the peer setting in the salt master configuration file, here are a number of configuration possibilities.

The simplest approach is to enable all communication for all minions, this is only recommended for very secure environments.

peer:
  .*:
    - .*

This configuration will allow minions with ids ending in example.com access to the test, ps, and pkg module functions.

peer:
  .*example.com:
    - test.*
    - ps.*
    - pkg.*

The configuration logic is simple, a regular expression is passed for matching minion ids, and then a list of expressions matching minion functions is associated with the named minion. For instance, this configuration will also allow minions ending with foo.org access to the publisher.

peer:
  .*example.com:
    - test.*
    - ps.*
    - pkg.*
  .*foo.org:
    - test.*
    - ps.*
    - pkg.*

GETTING INVOLVED

There are many ways to interact with the Salt community.

  Community

Join the Salt!

There are many ways to participate in and communicate with the Salt community.

Salt has an active IRC channel and a mailing list.

  Mailing List

Join the salt-users mailing list. It is the best place to ask questions about Salt and see whats going on with Salt development! The Salt mailing list is hosted by Google Groups. It is open to new members.

http://groups.google.com/group/salt-users

  IRC

The Salt IRC channel is hosted on the OFTC network. Connect to the OFTC server:

irc://irc.oftc.net:6667

and join us in #salt.

  Follow on Github

The Salt code is developed via Github. Follow Salt for constant updates on what is happening in Salt development:

https://github.com/thatch45/salt

  The Red45 Blog

News and thoughts on Salt and related projects is often posted on Thomas' blog The Red45:

http://red45.wordpress.com/

  Follow on ohloh

https://www.ohloh.net/p/salt

  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.

  Posting patches to the mailing list

If you have a patch for Salt, please format it via 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.

  Contributions Welcome!

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!

  Release notes and upgrade instructions

  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!

  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!

  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

  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

  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

  Salt 0.8.9 Release Notes

Salt 0.8.9 has finally arrived! Unfortunately this is much later than I had hoped to release 0.8.9, life has been very crazy over the last month. But despite challenges, Salt has moved forward!

This release, as expected, adds few new features and many refinements. One of the most exciting aspect of this release is that the development community for salt has grown a great deal and much of the code is from contributors.

Also, I have filled out the documentation a great deal. So information on States is properly documented, and much of the documentation that was out of date has been filled in.

  Download!

The Salt source can be downloaded from the salt github site:

https://github.com/downloads/thatch45/salt/salt-0.8.9.tar.gz

Or from PiPy:

http://pypi.python.org/packages/source/s/salt/salt-0.8.9.tar.gz

Here s the md5sum:

7d5aca4633bc22f59045f59e82f43b56

For instructions on how to set up Salt please see the tutorial

  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 master be running and the Salt minions point to the master.

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 returner). It is started with the 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).

  Instructions by operating system

•   Installing on Arch Linux

•   Installing on Debian or Ubuntu

•   Installing from the source tarball

  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:

    easy_install --install-layout=deb https://github.com/downloads/thatch45/salt/salt-0.9.0.tar.gz

    Please take note of the --install-layout=deb flag. This is important for a functioning installation of Salt.

  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 setup.py as root:

    tar xvf salt-0.9.0.tar.gz
    cd salt-0.9.0
    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

    Optional Dependencies:

•   gcc - dynamic Cython module compiling

  Configuring Salt

Salt configuration is very simple. The default configuration for the master will work for most installations and the only requirement for setting up a minion is to set the location of the master in the minion configuration file. The configuration files will be installed to /etc/salt and are named after the respective components, /etc/salt/master and /etc/salt/minion.

To make a minion check into the correct master simply edit the master variable in the minion configuration file to reference the master DNS name or IPv4 address.

See also

    For further information consult the configuration guide.

  Running Salt

1.  Start the master in the foreground (to daemonize the process, pass the -d flag):

    salt-master

2.  Start the minion in the foreground (to daemonize the process, pass the -d flag):

    salt-minion

See also

    salt-master manpage and salt-minion manpage

  Arch Linux init scripts

/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 master via the salt-key command. Once a 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

See also

    salt-key manpage

  Order your minions around

Now that you have a master and at least one minion communicating with each other you can perform commands on the minion via the salt command. Salt calls are comprised of three main components:

salt '<target>' <function> [arguments]

See also

    salt manpage

  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

See also

    Grains system

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'

See also

    the full list of modules

  arguments

Space-delimited arguments to the function:

salt '*' cmd.exec_code python 'import sys; print sys.version'

  New Features

  Salt Run

A big feature is the addition of Salt run, the salt-run command allows for master side execution modules to be made that gather specific information or execute custom routines from the master.

Documentation for salt-run can be found here:

http://saltstack.org/ref/runners.html

  Refined Outputters

One problem often complained about in salt was the fact that the output was so messy. Thanks to help from Jeff Schroeder a cleaner interface for the command output for the Salt cli has been made. This new interface makes adding new printout formats easy and additions to the capabilities of minion modules makes it possible to set the printout mode or outputter for functions in minion modules.

  Cross Calling Salt Modules

Salt modules can now call each other, the __salt__ dict has been added to the predefined references in minion modules. This new feature is documented in the modules documentation:

http://saltstack.org/ref/modules/index.html

  Watch Option Added to Salt State System

Now in Salt states you can set the watch option, this will allow watch enabled states to change based on a change in the other defined states. This is similar to subscribe and notify statements in puppet.

  Root Dir Option

Travis Cline has added the ability to define the option root_dir which allows the salt minion to operate in a subdir. This is a strong move in supporting the minion running as an unprivileged user

  Config Files Defined in Variables

Thanks again to Travis Cline, the master and minion configuration file locations can be defined in environment variables now.

  New Modules

Quite a few new modules, states, returners and runners have been made.

  New Minion Modules

  apt

Support for apt-get has been added, this adds greatly improved Debian and Ubuntu support to Salt!

  useradd and groupadd

Support for manipulating users and groups on Unix-like systems.

  moosefs

Initial support for reporting on aspects of the distributed file system, MooseFS. For more information on MooseFS please see: http://moosefs.org

Thanks to Joseph Hall for his work on MooseFS support.

  mount

Manage mounts and the fstab.

  puppet

Execute puppet on remote systems.

  shadow

Manipulate and manage the user password file.

  ssh

Interact with ssh keys.

  New States

  user and group

Support for managing users and groups in Salt States.

  mount

Enforce mounts and the fstab.

  New Returners

  mongo_return

Send the return information to a mongodb server.

  New Runners

  manage

Display minions that are up or down.

INDICES, GLOSSARY AND TABLES

•   genindex

•   modindex

•   search

AUTHOR
Thomas S. Hatch <thatch@gmail.com> and many others, please see the Authors file

COPYRIGHT
2011, Thomas S. Hatch