.. _syndic:

===========
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 attached 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 attached 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 :conf_master:`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
:conf_master:`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.

To sum up, you have those configuration options available on the master side:

    - :conf_master:`syndic_master`: MasterOfMaster ip/address
    - :conf_master:`syndic_master_port`: MasterOfMaster ret_port
    - :conf_master:`syndic_log_file`: path to the logfile (absolute or not)
    - :conf_master:`syndic_pidfile`: path to the pidfile (absolute or not)

Each Syndic must provide its own ``file_roots`` directory. Files will not be
automatically transferred from the master-master.

Running the Syndic
==================

The Syndic is a separate 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.

.. code-block:: bash

    # salt-syndic

.. note::

    If you have an exceptionally large infrastructure or many layers of
    syndics, you may find that the CLI doesn't wait long enough for the syndics
    to return their events.  If you think this is the case, you can set the
    :conf_master:`syndic_wait` value in the upper master config.  The default
    value is ``1``, and should work for the majority of deployments.


Topology
========
The ``salt-syndic`` is little more than a command and event forwarder. When a
command is issued from a higher-level master, it will be received by the
configured syndics on lower-level masters, and propagated to to their minions,
and other syndics that are bound to them further down in the hierarchy. When
events and job return data are generated by minions, they aggregated back,
through the same syndic(s), to the master which issued the command.

The master sitting at the top of the hierachy (the Master of Masters) will *not*
be running the ``salt-syndic`` daemon. It will have the ``salt-master``
daemon running, and optionally, the ``salt-minion`` daemon. Each syndic
connected to an upper-level master will have both the ``salt-master`` and the
``salt-syndic`` daemon running, and optionally, the ``salt-minion`` daemon.

Nodes on the lowest points of the hierarchy (minions which do not propogate
data to another level) will only have the ``salt-minion`` daemon running. There
is no need for either ``salt-master`` or ``salt-syndic`` to be running on a
standard minion.