Skip to content
Documentation
State Modules

State Modules

The state engine applies declarative YAML state files through these built-in modules. Each module manages one kind of resource idempotently — declare the desired state and the engine converges to it (and reports drift). See Using State Management for the state-file language and workflow.

System & core

  • cmd — Executes an arbitrary shell command via /bin/sh, gated by an idempotency guard (creates, onlyif, or unless).
  • file — Manages a single filesystem path — a regular file (content from inline text or a source), a directory, or a symlink — along with its owner, group, and mode.
  • group — Manages a Unix group, optionally pinning its numeric GID.
  • hostname — Manages the system static hostname.
  • package — Manages a Linux system package via the host’s native package manager — present at any version or pinned to an exact one, or removed.
  • service — Manages a system service’s running state and, optionally, its boot-enablement.
  • system — Manages system-level settings that don’t fit the other stdlib modules — login banners (/etc/motd, /etc/issue, /etc/issue.net), marker-gated reboots, and the system locale.
  • user — Manages a Linux user account — its UID/GID, primary group, home directory, login shell, GECOS comment, and supplementary groups.

Scheduled tasks

  • at — Manages one-shot scheduled jobs via the Linux at toolchain.
  • cron — Manages a single per-user crontab entry, identified by the declaration name and tagged with a marker comment so only that entry is owned.
  • systemd_timer — Manages a systemd .timer unit: it generates the unit from structured parameters and controls whether the timer is enabled at boot and currently armed.

Storage

  • disk — Manages the filesystem signature on a single block device: ensures a /dev/ path carries the declared fstype (formatting it with mkfs.<fstype>) or has no signature at all.
  • link — Manages a symbolic or hard link at a path.
  • lvm — Manages one LVM object per declaration — a Physical Volume (pv), a Volume Group (vg), or a Logical Volume (lv).
  • mount — Manages a filesystem’s /etc/fstab entry and its live mount state.
  • swap — Manages swap space — a swapfile or a swap partition/device — together with its /etc/fstab entry and live swapon state.

Network (base)

  • bond — Manages a Linux bonding (link-aggregation) interface — creates it at runtime via ip link with the declared mode, members, and link-monitor interval, with optional boot persistence to networkd or netplan.
  • bridge — Manages a Linux bridge interface at runtime via ip link, optionally enslaving member ports and persisting the bridge to the host network config.
  • network — Manages one network interface’s runtime configuration — IP addresses, MTU, and admin up/down — via the iproute2 ip tool, optionally rendering a boot-survive file (systemd-networkd or netplan) so the config persists across reboot.
  • route — Manages one entry in the kernel routing table at runtime via iproute2, keyed on (destination, table) (plus metric when set).
  • vlan — Manages a Linux 802.1Q VLAN interface — creates or removes a tagged interface on a parent link at runtime via ip link, optionally persisting it to the host network config.

Firewall (base)

  • firewall — Manages a single inbound allow rule for a named service or a port, dispatched to whichever firewall backend (iptables, nftables, or firewalld) is in use on the host.
  • firewalld — Manages one item — a service, a port, or a rich rule — in a firewalld zone via firewall-cmd --permanent, reloading so the change takes effect.
  • iptables — Manages a single iptables (or ip6tables) rule, identified by its full spec (chain + match args + target) rather than a name.
  • nftables — Manages a single nftables rule inside an existing chain, identified by its canonical text (family + table + chain + rule).

SSH & security

  • security — Manages SELinux settings (global mode and named booleans) and AppArmor per-profile modes.
  • ssh — Manages a single entry in a user’s ~/.ssh/authorized_keys — the classic authorized_key.present / .absent.

System config

  • kernel_module — Manages a Linux kernel module: ensures it is loaded (or unloaded) and, by default, that a keystone-managed /etc/modules-load.d entry persists the choice across reboots.
  • sysctl — Manages a kernel parameter (sysctl key): sets its runtime value and, by default, records it in a keystone-managed drop-in under /etc/sysctl.d/ so it survives a reboot.
  • timezone — Manages the system timezone.

Files & VCS

  • archive — Extracts an archive (tar, tar.gz, tar.bz2, or zip) into a target directory.
  • config — Manages a single key/value entry inside a config file — a flat keyvalue file or an INI file — touching only the line that defines the key and leaving every comment, blank line, and other key untouched.
  • git — Manages a git working tree on the agent: clones a repository to a path and optionally tracks a revision on the remote.
  • langpkg — Manages one language-ecosystem package per declaration via pip, npm, or gem — distinct from the OS-level package module.

Certificates

  • x509 — Manages a TLS certificate and its private key on disk (the declaration name is the certificate path) using crypto/x509 — no shelling out.