The Salt Event Bus and Reactor: Automatic Actions When Something Happens

SaltStack 28 min min read Updated: Nov 17, 2026 Advanced
The Salt Event Bus and Reactor: Automatic Actions When Something Happens
Advanced Topic 1 of 3

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

bash # Terminal 1 on the master: print every event sudo salt-run state.event pretty=True # Terminal 2: cause events salt '*' test.ping sudo systemctl restart salt-minion # on a minio
text salt/job/20261117101500123456/new {"fun": "test.ping", "tgt": "*", "user": "root", ...} salt/job/20261117101500123456/ret/web1 {"id": "web1", "return": true, "retcode": 0, "fun": "test.ping"} salt/minion/web1/start {"id": "web1", "pretag": null, "cmd": "_minion_event", ...} salt/auth {"act": "accept", "id": "web1", "result": true}
Tag patternWhen it fires
salt/minion/MINION_ID/startA minion connects and starts. Great for first-time setup
salt/authA minion asks to authenticate (new key, accepted, rejected)
salt/keyKey actions
salt/job/JID/newA job is published
salt/job/JID/ret/MINION_IDA 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/changeWhich minions are connected (if presence events are on)
Custom tags such as myco/deploy/finishedEvents you send yourself

Send Your Own Events

bash # From a minion salt-call event.send 'myco/deploy/finished' '{"app": "shop", "version": "1.4.0", "ok": true}' # From the master (or a script) salt-run event.send myco/deploy/started with_grains=True # From a state # - module.run or event state: event.send # From any program through salt-api: POST /events or /hook endpoints
yaml otify_deploy_done: event.send: - name: myco/deploy/finished - data: app: shop version: 1.4.0

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.

yaml # /etc/salt/master.d/reactor.conf reactor: - 'salt/minion/*/start': # tag pattern, globbing allowed - /srv/reactor/minion_start.sls - 'myco/deploy/finished': - /srv/reactor/post_deploy.sls - 'salt/auth': - /srv/reactor/auth_audit.sls
bash sudo mkdir -p /srv/reactor sudo systemctl restart salt-master # reactor config is read at start

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:

PrefixRunsEquivalent
localAn execution function on minionssalt 'tgt' func
runnerA runner on the mastersalt-run func
wheelA wheel function (master management: keys, config)salt-key, config
callerA function on a masterless/proxy minion with a caller clientsalt-call

Example 1: First Setup When a New Minion Starts

yaml # /srv/reactor/minion_start.sls {# Event data: data['id'] is the minion id #} {% set minion = data['id'] %} highstate_new_minion: local.state.apply: - tgt: {{ minion }} - args: - mods: common - kwarg: test: False sync_new_minion: local.saltutil.sync_all: - tgt: {{ minion }}
Idea: A new virtual machine boots, installs the minion, and its key is accepted. The salt/minion/*/start event fires. The reactor applies the common state automatically. Nobody runs a command.
The minion start event fires every time a minion restarts: Keep the reaction idempotent, and consider checking a grain like provisioned: True before running a heavy workflow. Otherwise a restart loop could create a loop of reactions.

Example 2: Accept Keys Automatically (Carefully)

yaml # /etc/salt/master.d/reactor.conf reactor: - 'salt/auth': - /srv/reactor/auto_accept.sls
yaml # /srv/reactor/auto_accept.sls {# Accept ONLY pending keys whose id matches our naming rule #} {% if data['act'] == 'pend' and data['id'].startswith('web-') and data['id'].endswith('.example.com') %} accept_key: wheel.key.accept: - args: - match: {{ data['id'] }} {% endif %}
Security: Auto-accepting keys by name is weak: anyone who can reach the master can claim a name. Combine it with network rules, pre-shared signed keys, or verify an external system (cloud API, ticket). See the Security lesson.

Example 3: React to a Beacon (Disk Full)

yaml # reactor.conf reactor: - 'salt/beacon/*/diskusage/': - /srv/reactor/clean_disk.sls # /srv/reactor/clean_disk.sls clean_old_logs: local.cmd.run: - tgt: {{ data['id'] }} - arg: - find /var/log -name '*.gz' -mtime +14 -delete notify_slack: runner.salt.cmd: - args: - fun: slack.post_message - channel: '#ops' - from_name: salt - message: 'Disk is full on {{ data["id"] }}, cleanup started.'

Example 4: Run an Orchestration From a Deploy Event

yaml # /srv/reactor/post_deploy.sls run_checks: runner.state.orchestrate: - args: - mods: orch.verify_deploy - pillar: app: {{ data['data']['app'] }} version: {{ data['data']['version'] }}

Reactor Syntax Details

ItemMeaning
tgtMinion target for local (glob by default)
tgt_typeglob, grain, compound, list, pcre, nodegroup
args / arg / kwargArguments to the function (list for positional, dict for keyword)
batchBatch size for local reactions
dataEvent data dictionary
tagThe event tag that matched
data['data']For custom events sent with event.send, your own payload is nested under data['data']

Debug the Reactor

bash sudo salt-run reactor.list # list configured reactions sudo salt-run reactor.add 'myco/test' reactors=/srv/reactor/test.sls # add at runtime sudo salt-run reactor.delete 'myco/test' sudo tail -f /var/log/salt/master # reactor errors appear here sudo salt-master -l debug # run the master in debug mode in a lab salt-run state.event pretty=True tagmatch='myco/*' # watch only some events salt-run event.send myco/test foo=bar # trigger a test reactio
ProblemCause and fix
Reaction never startsTag pattern mismatch, or master was not restarted after editing reactor.conf
Jinja error in reactor fileRender 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 shapeCheck whether args is a list or dict for that function. See the reactor docs and sys.argspec
Reaction loopsA reaction triggers an event that triggers the same reaction. Add a condition or use different tags
Very busy masterReactor 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.send first
  • Treat events from minions as untrusted input. Validate data before using it in commands

Practice Tasks

  1. Watch events with salt-run state.event while you restart a minion and run test.ping
  2. Write a reactor file that runs state.apply common when a minion starts
  3. Send a custom event with event.send and react with a message in a log file
  4. Add salt-run reactor.list and check your mapping
  5. 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.

Quick Summary: events have tag+data; state.event to watch; reactor.conf maps tag to SLS; local/runner/wheel; salt/minion/*/start; data['data'] for custom events.

Get Newsletter

Subscibe to our newsletter and we will notify you about the newest updates on Edugators