==========================
Salt Masterless Quickstart
==========================

.. _`Vagrant`: http://www.vagrantup.com/
.. _`salty-vagrant`: https://github.com/saltstack/salty-vagrant
.. _`salt-bootstrap`: https://github.com/saltstack/salt-bootstrap

Running a masterless salt-minion lets you use Salt's configuration management
for a single machine without calling out to a Salt master on another machine.

Since the Salt minion contains such extensive functionality it can be useful
to run it standalone. A standalone minion can be used to do a number of
things:

- Stand up a master server via States (Salting a Salt Master)
- Use salt-call commands on a system without connectivity to a master
- Masterless States, run states entirely from files local to the minion


It is also useful for testing out state trees before deploying to a production setup.


Bootstrap Salt Minion
=====================

The `salt-bootstrap`_ script makes bootstrapping a server with Salt simple
for any OS with a Bourne shell:

.. code-block:: bash

    wget -O - https://bootstrap.saltstack.com | sudo sh

See the `salt-bootstrap`_ documentation for other one liners. When using `Vagrant`_
to test out salt, the `salty-vagrant`_ tool will  provision the VM for you.

Telling Salt to Run Masterless
===================================

To instruct the minion to not look for a master when running
the :conf_minion:`file_client` configuration option needs to be set.
By default the :conf_minion:`file_client` is set to ``remote`` so that the
minion knows that file server and pillar data are to be gathered from the
master. When setting the :conf_minion:`file_client` option to ``local`` the
minion is configured to not gather this data from the master.

.. code-block:: yaml

    file_client: local

Now the salt minion will not look for a master and will assume that the local
system has all of the file and pillar resources.

.. note::

    When running Salt in masterless mode, do not run the salt-minion daemon.
    Otherwise, it will attempt to connect to a master and fail. The salt-call
    command stands on its own and does not need the salt-minion daemon.

Create State Tree
=================

Following the successful installation of a salt-minion, the next step is to create
a state tree, which is where the SLS files that comprise the possible states of the
minion are stored.

The following example walks through the steps necessary to create a state tree that
ensures that the server has the Apache webserver installed.

.. note::
    For a complete explanation on Salt States, see the `tutorial
    <http://docs.saltstack.org/en/latest/topics/tutorials/states_pt1.html>`_.

1. Create the ``top.sls`` file:

``/srv/salt/top.sls:``

.. code-block:: yaml

    base:
      '*':
        - webserver

2. Create the webserver state tree:

``/srv/salt/webserver.sls:``

.. code-block:: yaml

    apache:               # ID declaration
      pkg:                # state declaration
        - installed       # function declaration

.. note::

    The apache package has different names on different platforms, for
    instance on Debian/Ubuntu it is apache2, on Fedora/RHEL it is httpd
    and on Arch it is apache

The only thing left is to provision our minion using salt-call and the
highstate command.

Salt-call
---------

The salt-call command is used to run module functions locally on a minion
instead of executing them from the master. Normally the salt-call command
checks into the master to retrieve file server and pillar data, but when
running standalone salt-call needs to be instructed to not check the master for
this data:

.. code-block:: bash

    salt-call --local state.highstate

The ``--local`` flag tells the salt-minion to look for the state tree in the
local file system and not to contact a Salt Master for instructions.

To provide verbose output, use ``-l debug``:

.. code-block:: bash

    salt-call --local state.highstate -l debug

The minion first examines the ``top.sls`` file and determines that it is a part
of the group matched by ``*`` glob and that the ``webserver`` SLS should be applied.

It then examines the ``webserver.sls`` file and finds the ``apache`` state, which
installs the Apache package.

The minion should now have Apache installed, and the next step is to begin
learning how to write
:doc:`more complex states</topics/tutorials/states_pt1>`.