You are viewing docs from a branch that is no longer active. You might want to view docs for the 2015.8.x release instead.

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

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

syndic_master: MasterOfMaster ip/address

syndic_master_port: MasterOfMaster ret_port

syndic_log_file: path to the logfile (absolute or not)

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.

# 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 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 hierarchy (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 propagate 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.

Syndic and the CLI¶

In order for the high-level master to return information from minions that are below the syndic(s), the CLI requires a short wait time in order to allow the syndic(s) to gather responses from their minions. This value is defined in the ``syndic_wait` and has a default of five seconds.

While it is possible to run a syndic without a minion installed on the same machine, it is recommended, for a faster CLI response time, to do so. Without a minion installed on the syndic, the timeout value of syndic_wait increases significantly - about three-fold. With a minion installed on the syndic, the CLI timeout resides at the value defined in syndic_wait.

Note

To reduce the amount of time the CLI waits for minions to respond, install a minion on the syndic or tune the value of the syndic_wait configuration.