The Event Bus
Everything that happens in Salt creates an event: a minion starts, a job is published, a result returns, a key is accepted. Events travel on an event bus on the master. Each event has a tag (a path-like name) and data (a dictionary).
Watch Events Live
| Tag pattern | When it fires |
|---|---|
salt/minion/MINION_ID/start | A minion connects and starts. Great for first-time setup |
salt/auth | A minion asks to authenticate (new key, accepted, rejected) |
salt/key | Key actions |
salt/job/JID/new | A job is published |
salt/job/JID/ret/MINION_ID | A minion returns a result |
salt/run/JID/new, salt/wheel/... | Runner and wheel jobs |
salt/beacon/MINION_ID/BEACON/... | A beacon fired (next lesson) |
salt/presence/present, salt/presence/change | Which minions are connected (if presence events are on) |
Custom tags such as myco/deploy/finished | Events you send yourself |
Send Your Own Events
Reactor: Event In, Action Out
The reactor is a system on the master that watches the event bus. You map event tags to reactor SLS files. When an event matches, Salt renders the reactor SLS (it can use the event's data) and runs the actions inside it.
Reactor SLS Basics
A reactor SLS is YAML with Jinja. In the file you use data (the event data) and tag (the event tag). Each entry chooses an action type by its function name:
| Prefix | Runs | Equivalent |
|---|---|---|
local | An execution function on minions | salt 'tgt' func |
runner | A runner on the master | salt-run func |
wheel | A wheel function (master management: keys, config) | salt-key, config |
caller | A function on a masterless/proxy minion with a caller client | salt-call |
Example 1: First Setup When a New Minion Starts
salt/minion/*/start event fires. The reactor applies the common state automatically. Nobody runs a command.
provisioned: True before running a heavy workflow. Otherwise a restart loop could create a loop of reactions.
Example 2: Accept Keys Automatically (Carefully)
Example 3: React to a Beacon (Disk Full)
Example 4: Run an Orchestration From a Deploy Event
Reactor Syntax Details
| Item | Meaning |
|---|---|
tgt | Minion target for local (glob by default) |
tgt_type | glob, grain, compound, list, pcre, nodegroup |
args / arg / kwarg | Arguments to the function (list for positional, dict for keyword) |
batch | Batch size for local reactions |
data | Event data dictionary |
tag | The event tag that matched |
data['data'] | For custom events sent with event.send, your own payload is nested under data['data'] |
Debug the Reactor
| Problem | Cause and fix |
|---|---|
| Reaction never starts | Tag pattern mismatch, or master was not restarted after editing reactor.conf |
| Jinja error in reactor file | Render errors show in the master log. Reactor files do not have grains or pillar of the minion. They only see the event data |
| Wrong argument shape | Check whether args is a list or dict for that function. See the reactor docs and sys.argspec |
| Reaction loops | A reaction triggers an event that triggers the same reaction. Add a condition or use different tags |
| Very busy master | Reactor runs in worker threads. Keep reactor files light and hand heavy work to orchestration |
Best Practices
- Keep reactor SLS files short. Start an orchestration for multi-step work
- Make every reaction idempotent
- Use specific tag patterns, not
* - Add checks in Jinja (
if data['id'] ...) before you act - Log and notify. Send a message to chat when automation does something important
- Test reactions in a lab with
event.sendfirst - Treat events from minions as untrusted input. Validate data before using it in commands
Practice Tasks
- Watch events with
salt-run state.eventwhile you restart a minion and runtest.ping - Write a reactor file that runs
state.apply commonwhen a minion starts - Send a custom event with
event.sendand react with a message in a log file - Add
salt-run reactor.listand check your mapping - Make a reaction safer by adding a condition on the minion id pattern
Conclusion
The event bus carries everything that happens in Salt. The reactor maps event tags to reactor SLS files that run local, runner or wheel actions. Use it for first setup, notifications and self-healing, and keep reactions short, specific and idempotent.

