Common Salt State Modules: user, group, cron, archive, git, sysctl, ssh_auth, mount and More
Finding the Right State
bash
salt 'web1' sys.list_state_modules # all state modules
salt 'web1' sys.list_state_functions user # functions of the user state
salt 'web1' sys.state_doc user.present # help and arguments
# Online: the Salt documentation has a page for every module ("salt.states.user")
user and group
yaml
developers:
group.present:
- gid: 3000
alice:
user.present:
- uid: 2001
- fullname: Alice Smith
- shell: /bin/bash
- home: /home/alice
- createhome: True
- groups:
- developers
- sudo
- require:
- group: developers
olduser:
user.absent:
- purge: True # also delete the home folder
ssh_auth: Keys
yaml
alice_key:
ssh_auth.present:
- user: alice
- enc: ssh-ed25519
- name: AAAAC3NzaC1lZDI1NTE5AAAAIExampleKeyData
- comment: alice@laptop
- require:
- user: alice
# Keys from a file on the master
alice_keys_file:
ssh_auth.manage:
- user: alice
- ssh_keys:
- AAAAC3...key1
- AAAAC3...key2
cron
yaml
backup_job:
cron.present:
- name: /usr/local/bin/backup.sh >> /var/log/backup.log 2>&1
- user: root
- minute: 30
- hour: 2
- identifier: nightly-backup # a stable name so changes update the same entry
old_job:
cron.absent:
- identifier: old-job
pkgrepo: Package Repositories
yaml
# Debian family
docker_repo:
pkgrepo.managed:
- name: deb [arch=amd64] https://download.docker.com/linux/ubuntu {{ grains['oscodename'] }} stable
- file: /etc/apt/sources.list.d/docker.list
- key_url: https://download.docker.com/linux/ubuntu/gpg
- aptkey: False
# RHEL family
internal_repo:
pkgrepo.managed:
- name: internal
- humanname: Internal packages
- baseurl: https://repo.example.com/el9/
- gpgcheck: 1
- gpgkey: https://repo.example.com/RPM-GPG-KEY
- enabled: 1
archive.extracted and file.managed from URL
yaml
ode_exporter:
archive.extracted:
- name: /opt/node_exporter
- source: https://github.com/prometheus/node_exporter/releases/download/v1.8.2/node_exporter-1.8.2.linux-amd64.tar.gz
- source_hash: sha256=REAL_SHA256_VALUE
- archive_format: tar
- options: --strip-components=1
- enforce_toplevel: False
- if_missing: /opt/node_exporter/node_exporter # do not extract agai
git
yaml
app_code:
git.latest:
- name: https://git.example.com/team/app.git
- target: /opt/app
- rev: v1.4.0
- user: appsvc
- force_reset: True
- require:
- pkg: git
git:
pkg.installed: []
Editing Parts of a File
yaml
# Replace text with a regular expression
disable_root_ssh:
file.replace:
- name: /etc/ssh/sshd_config
- pattern: '^#?PermitRootLogin.*'
- repl: 'PermitRootLogin no'
- append_if_not_found: True
# Ensure a line exists (or is removed)
hosts_entry:
file.line:
- name: /etc/hosts
- content: '10.0.2.20 db.internal'
- mode: ensure
- location: end
# Append a block that Salt manages between markers
motd_block:
file.blockreplace:
- name: /etc/motd
- marker_start: '# BEGIN salt'
- marker_end: '# END salt'
- content: 'Managed by Salt'
- append_if_not_found: True
# INI file settings
app_ini:
ini.options_present:
- name: /etc/app/app.ini
- sections:
server:
port: 8080
debug: 'false'
sysctl, mount, host and system settings
yaml
et.ipv4.ip_forward:
sysctl.present:
- value: 0
- config: /etc/sysctl.d/90-salt.conf
vm.swappiness:
sysctl.present:
- value: 10
/data:
mount.mounted:
- device: UUID=1234-ABCD
- fstype: ext4
- mkmnt: True
- opts: defaults,noatime
- persist: True
db.internal:
host.present:
- ip: 10.0.2.20
Asia/Kolkata:
timezone.system: []
web1.example.com:
network.system:
- enabled: True
- hostname: web1.example.com
Services: running, dead, masked
yaml
cups:
service.dead:
- enable: False
avahi-daemon:
service.masked: []
chronyd:
service.running:
- enable: True
cmd: Last Resort, With Guards
yaml
build_index:
cmd.run:
- name: /usr/local/bin/build-index.sh
- cwd: /opt/app
- runas: appsvc
- creates: /opt/app/index.db
- env:
- LANG: C
wait_for_port:
cmd.wait_script:
- source: salt://scripts/wait-port.sh
- args: 8080
- watch:
- service: app_service
Other States You Will Meet
| State module | Use |
|---|---|
pkg.latest, pkg.removed, pkg.purged, pkg.uptodate | Keep packages current or remove them |
pip.installed, virtualenv.managed | Python packages and virtual environments |
docker_container, docker_image | Docker (needs the Docker Python library) |
firewalld, iptables, nftables | Firewall rules |
selinux.mode, selinux.boolean, selinux.port_policy_present | SELinux |
file.recurse | Copy a folder from the master |
file.serialize | Write a data structure as JSON, YAML or TOML |
augeas.change | Edit config files with Augeas |
alternatives.set | Debian and RHEL alternatives |
postgres_*, mysql_* | Database users, databases and grants |
win_* (win_servermanager, win_firewall, reg) | Windows (see the Windows lesson) |
test.nop, test.succeed_without_changes, test.fail_with_changes | Testing helpers |
yaml
/etc/app/settings.json:
file.serialize:
- dataset:
port: 8080
features:
beta: false
servers: [a, b, c]
- serializer: json
- mode: '0644'
Practice Tasks
- Create a state file that adds two users and an SSH key with
ssh_auth.present - Add a nightly cron job and verify with
salt web1 cron.list_tab root - Download and extract a small tarball with
archive.extractedand a checksum - Use
file.replaceto set one line in/etc/ssh/sshd_config, withcheck_cmdon the real file viafile.managedas a second version - Use
sys.state_docto read the help of two new state modules
Conclusion
Most server work is covered by about twenty state modules. Find them with sys.list_state_modules and sys.state_doc, use dedicated states (user, cron, archive, sysctl, mount) over cmd.run, and always add guards to commands.
Quick Summary: user/group/ssh_auth; cron identifier; pkgrepo; archive.extracted + hash; git.latest; file.replace/line/blockreplace; sysctl; mount; sys.state_doc.

