salt-run

Show status of all minions

$ salt-run manage.status

$ salt-run manage.up

salt-run [options] runner-module.runner-function [arguments...]

-l, --log-level
    Set the console log reporting level to LEVEL (e.g., info, warning, error, debug).

-o, --output
    Specify the output format for the command's return data (e.g., json, yaml, pprint, raw).

-t, --timeout
    Set the timeout in seconds for runner execution. Defaults to 60 seconds.

-c, --config-dir
    Specify the path to the Salt configuration directory. Defaults to /etc/salt.

--local
    Execute in local mode, without requiring a Salt master. This is mainly for testing or specific standalone operations.

--versions-report
    Display program version and exit.

-h, --help
    Show the program's help message and exit.

The salt-run command is a utility within the SaltStack automation and configuration management system. It is specifically designed to execute runner modules directly on the Salt master server. Unlike the primary salt command, which sends commands to Salt minions, salt-run operates master-side to perform administrative, analytical, or orchestration tasks that do not require minion interaction. Common uses include managing Salt keys, querying the master's status, orchestrating multi-minion deployments, or executing custom administrative scripts defined as runner modules. It provides a powerful interface for managing the Salt infrastructure itself.

Execution Context: salt-run commands are executed on the Salt master server, not on minions.
Permissions: The user executing salt-run on the master needs appropriate file system and Salt configuration permissions to access runner modules and master-side resources.
Impact: Runners can perform powerful operations (e.g., key deletion, orchestration of states). Use with caution and ensure you understand the runner's function.
Dependency on Master: Typically requires a running Salt master daemon, unless the --local flag is used for specific testing scenarios.

Runner modules are Python modules located on the Salt master (typically in /srv/salt/_runners or directories specified in the master config). They contain functions designed to be executed directly by the Salt master to perform master-side operations. These modules are not executed by minions.

Some frequent applications of salt-run include:
Key Management: E.g., salt-run manage.up (list connected minions), salt-run manage.down (list disconnected minions), salt-run manage.raw_minions (list all minions known by the master).
Orchestration: E.g., salt-run state.orch my.orchestration.state (execute a Salt orchestration state on the master).
Master Status/Maintenance: E.g., salt-run cache.clear_all (clear all master-side minion caches).
External Authentication (eAuth): Runners can be used in conjunction with eAuth systems to provide controlled access to Salt functionality.

SaltStack was initially released in 2011, and salt-run has been a fundamental component since its early versions. It was conceived to provide a distinct interface for master-side administrative tasks, separating them from minion-targeting operations. Over time, as SaltStack's capabilities expanded, so did the variety and complexity of available runner modules, solidifying salt-run's role as a critical tool for managing Salt infrastructure and orchestrating complex deployments.

salt(1), salt-call(1), salt-master(1), salt-minion(1)