Salt Execution Modules: pkg, service, file, cmd, user, network and the sys Helpers

SaltStack 26 min min read Updated: Nov 17, 2026 Beginner
Salt Execution Modules: pkg, service, file, cmd, user, network and the sys Helpers
Beginner Topic 1 of 3

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

ReturnMeaning
True / dataThe 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

  1. Use sys.list_functions and sys.doc to find three functions of the file module you did not know
  2. Install htop on all minions with pkg.install, check with pkg.version
  3. Restart a service on one minion, then check service.status
  4. Collect disk usage from all minions as a table and as JSON
  5. 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.

Get Newsletter

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