salt/doc/index.rst

:orphan:

.. _contents:

.. |vid| image:: /_static/film_link.png
    :class: math

Get started with Salt
=====================

.. sidebar:: Presentations

    A list of `presentations and interviews on Salt`_ (including the FLOSS
    Weekly interview).

.. _`presentations and interviews on Salt`: http://saltstack.org/learn/

Salt is an open source tool to manage your infrastructure. Easy enough to get
running in minutes and fast enough to manage tens of thousands of servers (and
still get a response back in *seconds*).

Execute arbitrary shell commands or choose from dozens of pre-built modules of
common (or complex) commands. Target individual servers or groups of servers
based on name, defined roles, or a variety of system information such as
hardware, software, operating system, current version, current environment, and
many more.

Bring your servers up to a known configured state by writing simple lists of
items and defining attributes on those lists—no need to learn yet another
language.

Read the :doc:`Salt overview <topics/index>` for a more thorough description.

Salt (Masterless) Quickstart
----------------------------

Install salt-minion and provision a webserver in 3 easy steps. The fastest way to start
using salt's configuration management.

:doc:`Salt Quickstart </topics/tutorials/quickstart>`


Tutorial 1: Remote execution
----------------------------

.. sidebar:: |vid| Screencasts

    Watch the `remote execution screencast`__.

.. __: http://blip.tv/saltstack/salt-installation-configuration-and-remote-execution-5713423

The quickest way to see Salt in action is to run a command on a :term:`minion`
host from the :term:`master` host. This is widely known as :term:`remote
execution` — executing commands on remote hosts.

1.  :doc:`Installation </topics/installation/index>`
2.  :doc:`Configure the minion <topics/configuration>`
3.  :doc:`Run remote commands <topics/tutorials/modules>`

Tutorial 2: Configuration management
------------------------------------

Now that you have the basics out of the way, learn to use Salt to configure
your servers. This is widely known as :term:`configuration management` —
installing packages, configuring users and services, and much more.

1.  :doc:`Getting Started with States<topics/tutorials/starting_states>`
2.  :doc:`Basic config management <topics/tutorials/states_pt1>`
3.  :doc:`Less basic config management <topics/tutorials/states_pt2>`
4.  :doc:`Advanced techniques <topics/tutorials/states_pt3>`

Salt in depth
=============

Setting up and using Salt is a simple task but its capabilities run much, much
deeper. Gaining a better understanding of how Salt works will allow you to
truly make it work for you.

.. sidebar:: More tutorials!

    * :doc:`Bootstraping Salt on EC2 <topics/tutorials/bootstrap_ec2>`
    * :doc:`Preseeding Minions with Accepted Keys <topics/tutorials/preseed_key>`

.. contents:: The components of Salt
    :local:
    :depth: 2

:doc:`Targeting </topics/targeting/index>`
------------------------------------------

Targeting is specifying which minions should execute commands or manage server
configuration.

:doc:`Globbing and regex </topics/targeting/globbing>`
    Match minions using globbing and regular expressions.

:doc:`Grains </topics/targeting/grains>`
    Match minions using bits of static information about the minion such as
    OS, software versions, virtualization, CPU, memory, and much more.

:doc:`Node groups </topics/targeting/nodegroups>`
    Statically define groups of minions.

:doc:`Compound matchers </topics/targeting/compound>`
    Combine the above matchers as a single target.

:doc:`Batching execution </topics/targeting/batch>`
    Loop through all matching minions so that only a subset are executing a
    command at one time.

Remote execution
----------------

Remote execution is the core functionality of Salt. Running pre-defined or
arbitrary commands on remote hosts.

**Modules**
    Salt modules are the core of remote execution. They provide
    functionality such as installing a package, restarting a service,
    running a remote command, transferring a file — and the list goes on.

    :doc:`Full list of modules </ref/modules/all/index>`
        The giant list of core modules that ship with Salt
        (And there are even more in the `salt-contrib`_ repository!)

    :doc:`Writing modules <ref/modules/index>`
        A guide on how to write Salt modules.

**Returners**
    Salt returners allow saving minion responses in various datastores or
    to various locations in addition to display at the CLI.

    :doc:`Full list of returners </ref/returners/all/index>`
        Store minion responses in Redis, Mongo, Cassandra or more.

    :doc:`Writing returners <ref/returners/index>`
        If we're missing your favorite storage backend, webservice, or you
        need a custom endpoint returners are *tiny* and simple to write.

Configuration management
------------------------

Building on the remote execution core is a robust and flexible config
management framework. Execution happens on the minions allowing
effortless, simultaneous configuration of thousands of hosts.

**States**
    Express the state of a host using small, easy to read, easy to
    understand configuration files. No programming required (unless you
    want to).

    :doc:`Full list of states <ref/states/all/index>`
        Install packages, create users, transfer files, start services, and
        much more.

    :doc:`Using states <ref/states/index>`
        You've seen the big list of available states, now learn how to call
        them.

    :doc:`Highstate data structure <ref/states/highstate>`
        A dry vocabulary and technical representation of the configuration
        format that states represent.

**Renderers**
    Write state configuration files in the language, templating engine, or
    file type of your choice. The world doesn't need yet another DSL.

    :doc:`Full list of renderers <ref/renderers/all/index>`
        YAML? JSON? Jinja? Mako? Wempy? Python? We got you covered. (And if
        we don't, new renderers are *tiny* and easy to write.)

    :doc:`Renderers <ref/renderers/index>`
        Salt states are only concerned with the ultimate highstate data
        structure. How you create that data structure isn't our business.
        Tweak a config option and use whatever you're most comfortable
        with.

Miscellaneous topics
--------------------

Salt is many splendid things.

:doc:`File Server <ref/file_server/index>`
    Salt can easily and quickly transfer files (in fact, that's how Salt
    States work). Even under load, files are chunked and served.

:doc:`Syndic <ref/syndic>`
    A seamless master of masters. Scale Salt to thousands of hosts or
    across many different networks.

:doc:`Peer communication <ref/peer>`
    Allow minions to communicate amongst themselves. For example, configure
    one minion by querying live data from all the others. With great power
    comes great responsibility.

:doc:`Running Salt without root <topics/nonroot>`
    The Salt daemons can be run as an unprivileged user.

:doc:`Firewall settings and Salt <topics/tutorials/firewall>`
    A tutorial covering how to properly firewall a Salt Master server.

:doc:`Cron and Salt States <topics/tutorials/cron>`
    A tutorial covering how to properly use cron to schedule when a 
    minion updates its state.

:doc:`Network topology <ref/topology>`
    At it's core, Salt is a highly scalable communication layer built on
    top of ZeroMQ that enables remote execution and configuration
    management. The possibilities are endless and Salt's future looks
    bright.

:doc:`Testing Salt <topics/tests/index>`
    A howto for writing unit tests and integration tests.

:doc:`Python API interface <ref/python-api>`
    Use Salt programmatically from your own scripts and programs easily and
    simply via ``import salt``.

:doc:`Automatic Updates and Frozen Binary Deployments <topics/tutorials/esky>`
    Use a frozen install to make deployments easier (Even on Windows!). Or
    take advantage of automatic updates to keep your minions running your
    latest builds.

:doc:`Windows Software Manager / Package Repository <ref/windows-package-manager>`
    Looking for an easy way to manage software on all your Windows machines? Do
    you feel left out of all the package manager magic found in yum and apt?
    Search no more! Salt has an integrated software package manager for your
    Windows machines! Install software hosted on your master, somewhere on your
    network, or anywhere http, https, and ftp work.

Reference
---------

:doc:`Command-line interface <ref/cli/index>`
    Read the Salt manpages.

:doc:`Full list of master settings <ref/configuration/master>`
    Read through the heavily-commented master configuration file.

:doc:`Full list of minion settings <ref/configuration/minion>`
    Read through the heavily-commented minion configuration file.

:doc:`Full table of contents </contents>`
    Dense but complete.

More information about the project
----------------------------------

:doc:`Release notes </topics/releases/index>`
    Where we've been.

:doc:`Community </topics/community>`
    How you can get involved.

:doc:`Salt Development </topics/development/index>`
    Information for Hacking on Salt

.. _`salt-contrib`: https://github.com/saltstack/salt-contrib
.. _`salt-states`: https://github.com/saltstack/salt-states