A step calls a tool by name and passes it arguments. This page lists every tool, what it does, and which of them a dry run can simulate against the host rather than merely display.
How to read a tool#
A tool name is namespace.verb, and it goes in a step's tool field:
- name: Allow HTTPS through the firewall
tool: ufw.allow
args:
port: 443
protocol: tcpEvery tool also receives the target host implicitly, so server_name is never something
you pass. Arguments listed as none take nothing beyond the target.
The dry run column says whether the tool supports a real read-only check. A yes
means a dry run contacts the host and reports would create, would change or no change. A blank means the dry run shows you the resolved command it would execute, but
does not predict its effect. That distinction is explained in full under
dry runs.
Choosing a tool over a raw command#
ssh.cmd runs any shell command, which makes it the tool that can do anything and the
tool that can tell you least. Opafra cannot preview it, cannot report whether it changed
anything, and cannot make it idempotent.
Prefer a named tool where one fits. file.lineinfile will not duplicate a line it already
wrote; the equivalent echo >> will, every time the plan runs. apt.install reports that
a package was already present; ssh.cmd: apt-get install -y nginx reports that a command
exited zero.
Every tool#
| Tool | What it does | Arguments | Dry run |
|---|---|---|---|
apt.install | Install packages via apt-get (non-interactive) | packages | yes |
apt.update_upgrade | Update apt cache and upgrade all installed packages | none | |
archive.extract | Extract a gzipped tar archive to a directory | archive_path, dest_dir | |
backup.create_tar | Create a timestamped tar.gz backup of a directory | backup_path, source_path | |
backup.rotate | Delete backup files older than N days from a directory | backup_dir, days | |
certbot.install | Install Certbot and the nginx plugin via apt-get | none | |
certbot.obtain | Obtain an SSL certificate for a domain using Certbot + nginx | domain, email | |
certbot.renew | Renew all Certbot certificates quietly | none | |
cron.add | Add a cron entry (idempotent - will not duplicate an identical line) | schedule, command | yes |
cron.list | List all cron jobs in the current crontab | none | |
disk.usage | Show disk usage for a given path | path | |
disk.cleanup | Delete files older than N days under a path | path, days | |
docker.run | Run a Docker container in detached mode | args, image | |
docker.compose_up | Start services defined in a Docker Compose file | compose_path | |
docker.compose_down | Stop and remove services defined in a Docker Compose file | compose_path | |
file.template | Write text content directly to a file on the remote server | remote_path, content | |
file.lineinfile | Ensure a line is present in or absent from a config file (idempotent, like Ansible lineinfile) | path, regexp, line, state | yes |
file.backup | Copy a remote file to a backup path | remote_path, backup_path | yes |
git.clone | Clone a git repository to a destination path | repo, dest | |
git.pull | Pull latest changes in an existing git repository | repo_path | |
helm.upgrade | Install or upgrade a Helm release with retry on lock conflicts | release, chart, helm_args | |
helm.status | Show the status of a Helm release | namespace, release | |
helm.install | Install a Helm chart from a repository | chart_name, chart_repo, helm_args | |
kube.apply | Apply a Kubernetes manifest to a namespace | manifest, namespace | |
kube.wait_rollout | Wait for a Kubernetes rollout to complete | kind, name, namespace, timeout | |
log.tail | Show the last N lines of a log file | lines, log_path | |
logs.grep | Search a log file for a pattern and return last N matches | pattern, log_file, lines | |
monitoring.disk_alert | Alert if any filesystem is above a usage threshold | threshold | |
monitoring.cpu_load | Show 1/5/15 minute CPU load averages | none | |
monitoring.swap_usage | Show current swap memory usage as a percentage | none | |
monitoring.memory_check | Show current RAM usage as a percentage | none | |
mysql.dump | Dump a MySQL database to a SQL file using mysqldump | host, user, password, database, output_file | |
network.ping | Ping a host N times and report packet loss | count, host | |
network.port_check | Check if a TCP port is open on a remote host | host, port | |
network.curl_health | Make an HTTP health-check request and return status code | url | |
nginx.install | Install nginx via apt-get | none | yes |
nginx.config | Write an nginx configuration file to the server | config_content, config_path | |
nginx.reload | Test nginx config and reload the service | none | yes |
nginx.test_config | Test the nginx configuration syntax (read-only; falls back to sudo if the config is unreadable) | none | |
nodejs.install | Install a specific Node.js version from NodeSource | version | |
nodejs.install_pm2 | Install PM2 globally and configure it to start on boot | none | |
npm.install | Install an npm package inside an application directory | app_path, package | |
pm2.start | Start a Node.js application with PM2 and save the process list | app_path, entry_file, app_name | |
pm2.restart | Restart a PM2-managed application | app_name | |
pm2.logs | Show recent PM2 logs for an application | app_name, lines | |
postgres.dump | Dump a PostgreSQL database to a SQL file using pg_dump | password, host, user, database, output_file | |
process.list | List running processes matching a pattern | pattern | |
rsync.sync | Sync files between two paths using rsync | source, destination | |
security.disable_root_ssh | Disable root SSH login (matches commented, prohibit-password and spaced variants) | none | |
service.health | Check whether a systemd service is active | service | |
ssh.cmd | Run any shell command on the target server over SSH | command | |
ssh.ping | Check SSH reachability of the target server | none | |
ssh.script.file | Upload and execute a script file on the target server | script_name, script_args, cleanup | |
ssl.check_expiry | Check SSL certificate expiry dates for a domain | domain | |
system.uptime | Show how long the server has been running | none | |
systemd.status | Show the status of a systemd service | service | |
systemd.start | Start a systemd service | service | yes |
systemd.restart | Restart a systemd service | service | yes |
systemd.enable | Enable a systemd service to start on boot | service | yes |
template.deploy | Deploy a config template to a target server path | template_id, template_name, target_path, variables, environment_scope, owner, mode, backup | yes |
template.verify | Verify a deployed config template matches the expected hash | target_path, deployment_id | |
ufw.enable | Enable the UFW firewall | none | yes |
ufw.allow | Allow a port/protocol through UFW | port, protocol | yes |
ufw.status | Show UFW firewall rules and status | none | |
user.create | Create a new Linux user with a home directory | username | yes |
user.exists | Check whether a Linux user account exists | username | |
user.delete | Delete a Linux user account | userdel_flags, username | yes |
user.set_shell | Change the default shell for a Linux user | shell, username | |
user.ensure_group | Create a Linux group if it does not already exist | group | |
user.add_to_group | Add a Linux user to a supplementary group | username, group | |
user.set_groups | Set the full list of supplementary groups for a Linux user | groups, username | |
user.set_password | Set the password for a Linux user account | username, password | |
user.add_ssh_key | Add an SSH public key to a user's authorized_keys | username, ssh_key | |
yum.install | Install packages via yum (RPM-based systems) | packages | yes |
Namespaces at a glance#
| Namespace | Tools | Covers |
|---|---|---|
apt, yum, npm | 4 | Package installation |
archive, backup, rsync | 4 | Files moved, packed and rotated |
certbot, ssl | 4 | Certificates and expiry |
cron | 2 | Scheduled entries on the host |
disk, system, process, monitoring | 8 | Reading host state: usage, load, memory, processes |
docker, helm, kube | 8 | Containers and clusters |
file, template | 5 | Config files, written and verified |
git | 2 | Repositories on the host |
log, logs | 2 | Reading and searching logs |
mysql, postgres | 2 | Database dumps |
network | 3 | Reachability and health checks |
nginx | 4 | Install, configure, test, reload |
nodejs, pm2 | 5 | Node runtimes and process management |
security, ufw | 4 | Hardening and firewall rules |
service, systemd | 5 | Service state |
ssh | 3 | Raw commands and uploaded scripts |
user | 9 | Accounts, groups, shells and keys |
Arguments and variables#
Any argument can be a literal or a {{ vars.x }} reference resolved at run time from plan
variables, environment variables, or values supplied when the run starts.
- name: Allow the app port
tool: ufw.allow
args:
port: "{{ vars.app_port }}"
protocol: tcpA variable that stays unresolved is empty at run time, which is rarely what was meant. A dry run lists every unresolved variable it found, which is the cheapest place to catch it.
Arguments naming a credential should be a secret:// reference rather than a literal.
References are resolved on the host at the moment of use and are redacted everywhere a
command is displayed or logged.
Next steps#
- Dry runs for what the dry run column actually means
- Core concepts for how steps, tools and plans fit together