Salt Execution Modules: pkg, service, file, cmd, user, network and the sys Helpers
What Is an Execution Module?
An execution module is a Python file that provides functions you can call on minions, for example pkg.install or service.restart. The format is module.function. Salt ships with hundreds of modules.
bash
salt 'web*' pkg.install nginx # module pkg, function install, argument nginx
salt 'web*' service.restart nginx # module service
salt '*' cmd.run 'df -h /' # module cmd, run a shell command
salt '*' user.list_users # no arguments needed
Remote execution vs states: Execution modules do something now (install, restart). They are great for quick actions and information. States (next section) describe a wanted condition and are safe to repeat. A state usually calls an execution module under the hood.
Discover Modules and Functions
bash
salt 'web1' sys.list_modules # all modules on the minion
salt 'web1' sys.list_functions pkg # functions in the pkg module
salt 'web1' sys.doc pkg.install # full help text with examples
salt 'web1' sys.argspec pkg.install # argument names and defaults
salt 'web1' sys.list_state_modules # state modules
salt 'web1' sys.state_doc pkg.installed # help for a state function
# Same help on the minion itself, without a master:
salt-call --local sys.doc service
The built-in manual: sys.doc module.function is the fastest way to learn a function. It works offline and always matches the exact Salt version you run.
Positional and Keyword Arguments
bash
salt 'web1' pkg.install nginx # positional
salt 'web1' pkg.install pkgs='["nginx","git"]' # keyword argument, JSON list
salt 'web1' pkg.install nginx version=1.24.0-2 # keyword argument
salt 'web1' file.replace /etc/app.conf pattern='port=80' repl='port=8080'
salt 'web1' cmd.run 'ls -l' cwd=/etc runas=alice # run as another user, in a folder
salt 'web1' cmd.run 'echo $HOME' env='{"LANG":"C"}'
pkg: Packages
bash
salt '*' pkg.refresh_db # update package metadata (apt update / dnf makecache)
salt '*' pkg.list_pkgs # installed packages with versions
salt '*' pkg.version openssl # version of one package
salt '*' pkg.latest_version openssl # newest available version
salt '*' pkg.list_upgrades # available updates
salt web1 pkg.install nginx
salt web1 pkg.remove nginx
salt web1 pkg.upgrade # upgrade everything (test with a batch first!)
salt web1 pkg.hold nginx # hold a package version (apt)
salt web1 pkg.file_list nginx # files in a package
pkg is a virtual module: on Debian family it uses aptpkg, on RedHat family yumpkg or dnf, on Windows win_pkg. The same command works everywhere. That is one of Salt's strengths.
service: Services
bash
salt '*' service.status sshd
salt web1 service.start nginx
salt web1 service.stop nginx
salt web1 service.restart nginx
salt web1 service.reload nginx
salt web1 service.enable nginx # start at boot
salt web1 service.disable nginx
salt web1 service.get_all # all services
salt web1 service.available nginx # does the service exist?
file: Files and Directories
bash
salt web1 file.file_exists /etc/nginx/nginx.conf
salt web1 file.read /etc/hostname # contents (small files only)
salt web1 file.stats /etc/passwd
salt web1 file.mkdir /opt/app/logs mode=0755
salt web1 file.append /etc/motd 'Maintenance on Friday'
salt web1 file.replace /etc/ssh/sshd_config pattern='^#?PermitRootLogin.*' repl='PermitRootLogin no'
salt web1 file.remove /tmp/old.txt
salt web1 file.get_hash /etc/passwd sha256
salt web1 file.check_perms /etc/shadow '{}' root root 0000 # advanced check
cmd: Run Commands
bash
salt '*' cmd.run 'uptime' # return stdout and stderr as text
salt '*' cmd.run_all 'ls /nonexistent' # return a dict: retcode, stdout, stderr, pid
salt '*' cmd.retcode 'systemctl is-active nginx' # only the exit code
salt '*' cmd.script salt://scripts/cleanup.sh args='-v' # run a script stored on the master
salt '*' cmd.run 'whoami' runas=deploy
salt '*' cmd.run 'sleep 120' timeout=180 # command timeout
salt 'win*' cmd.run 'Get-Service W32Time' shell=powershell
cmd.run is powerful, so be careful: It runs any command as root. Quote carefully (single quotes outside), avoid putting passwords in commands (they appear in logs and the job cache), and prefer a specific module (service.restart) over cmd.run 'systemctl restart ...'.
user and group
bash
salt web1 user.add alice uid=2001 shell=/bin/bash
salt web1 user.info alice
salt web1 user.list_users
salt web1 user.chgroups alice 'sudo,developers' append=True
salt web1 user.delete alice remove=True # remove the home folder too
salt web1 group.add developers gid=3000
salt web1 group.info developers
salt web1 shadow.set_password alice '$6$salt$hash...' # set a PASSWORD HASH, not clear text
Information Modules
bash
salt '*' status.uptime
salt '*' status.loadavg
salt '*' status.meminfo
salt '*' status.diskusage
salt '*' disk.usage
salt '*' disk.percent /
salt '*' network.interfaces
salt '*' network.ip_addrs
salt '*' network.ping 8.8.8.8
salt '*' network.netstat
salt '*' ps.top
salt '*' ps.pgrep nginx
salt '*' system.get_system_date_time
salt '*' timezone.get_zone
salt '*' sysctl.get net.ipv4.ip_forward
salt '*' cron.list_tab root
salt '*' mount.active
salt '*' grains.items
salt '*' grains.get os_family
salt '*' test.ping
Copy Files with cp and salt-cp
bash
# From master to minions (small files, uses the event bus)
salt-cp 'web*' /srv/files/app.conf /etc/app/app.conf
# Minion pulls a file from the master file server (better for big files)
salt 'web*' cp.get_file salt://configs/app.conf /etc/app/app.conf
salt 'web*' cp.get_dir salt://web/static /var/www/
salt 'web*' cp.get_url https://example.com/tool.tgz /tmp/tool.tgz
# Minion sends a file TO the master (needs file_recv: True in master config)
salt 'web1' cp.push /var/log/nginx/error.log
Archives, Git, Cron, SSH and More
bash
salt web1 archive.tar xf /tmp/app.tar.gz dest=/opt/
salt web1 archive.unzip /tmp/app.zip /opt/app
salt web1 git.clone /opt/app https://git.example.com/app.git
salt web1 git.pull /opt/app
salt web1 ssh.set_auth_key alice 'AAAAC3...' enc=ed25519
salt web1 firewalld.add_port public 8080/tcp permanent=True
salt web1 docker.ps
salt web1 pip.install requests bin_env=/opt/venv/bin/pip
salt web1 mysql.db_list
Choosing the Output Format
bash
salt '*' grains.item os --out=json
salt '*' grains.item os --out=yaml
salt '*' status.diskusage --out=table
salt '*' cmd.run 'hostname' --out=txt
salt '*' test.ping --out=newline_values_only
salt '*' test.ping --out=json --out-indent=-1 --static # one line JSON, good for scripts
Reading the Result
| Return | Meaning |
True / data | The function ran. Check the data |
Minion did not return. [No response] | No answer before the timeout (minion down, slow job, or key problem) |
'pkg.install' is not available. | Module not loaded on that minion (OS differences, missing dependency) |
ERROR: ... | The function failed. Read the message |
Minion did not return. [Not connected] | The minion is not connected to the master now |
Modules Are Not Always Idempotent
pkg.install nginx is safe to repeat (it does nothing if installed). But file.append, cmd.run 'echo x >> file' and user.add (error if exists) are not. For repeatable work use states (the next section).
Practice Tasks
- Use
sys.list_functions and sys.doc to find three functions of the file module you did not know
- Install
htop on all minions with pkg.install, check with pkg.version
- Restart a service on one minion, then check
service.status
- Collect disk usage from all minions as a table and as JSON
- Run
cmd.run_all on a command that fails and read retcode and stderr
Conclusion
Execution modules are the building blocks you call as module.function. Learn to discover them with sys.doc, prefer specific modules over cmd.run, and remember that remote execution is for now, while states are for repeatable configuration.
Quick Summary: module.function args; sys.doc/sys.list_functions; pkg/service/file/cmd/user; cmd.run_all; salt-cp vs cp.get_file; not always idempotent.