Driftless Configuration Reference

Comprehensive reference for all available configuration components in Driftless.

This documentation is auto-generated from the Rust source code.

Overview

Driftless provides three main configuration components that work together to manage systems:

Configuration Operations (apply): Define and enforce desired system state
Facts Collectors (facts): Gather system metrics and inventory information
Log Sources/Outputs (logs): Handle log collection and forwarding

Configuration Operations (`apply`)

Configuration operations define desired system state and are executed idempotently. Each operation corresponds to a specific aspect of system configuration management.

Task Result Registration and Conditions

All configuration operations support special fields for conditional execution and capturing results:

when: An optional expression (usually containing variables) that determines if the task should be executed. If the condition evaluates to false, the task is skipped.
register: An optional variable name to capture the result of the task execution. The captured data varies by task type and can be used in subsequent tasks using template expansion (e.g., {{ my_var.stdout }}). This field only appears in the documentation for tasks that provide output results.

Command Execution

command

Description: Command execution task

Required Fields:

command (String): Command to execute
env (HashMap<String, String>): Environment variables
exit_code (i32): Expected exit code (default: 0)
idempotent (bool): Whether command should be idempotent (only run if not already applied)
stream_output (bool): Whether to stream output in real-time (useful for long-running commands)

Optional Fields:

cwd (Option): Working directory for command execution
description (Option): Optional description of what this task does

Human-readable description of the task’s purpose. Used for documentation and can be displayed in logs or reports.
group (Option): Whether to run command as a specific group
register (Option): Optional variable name to register the task result in
user (Option): Whether to run command as a specific user
when (Option): Optional condition to determine if the task should run

Registered Outputs:

changed (bool): Whether the command was actually run
rc (i32): The exit code of the command
stderr (String): The standard error of the command
stdout (String): The standard output of the command

Examples:

Run a simple command:

YAML Format:

- type: command
  description: "Update package list"
  command: apt-get update

JSON Format:

{
  "type": "command",
  "description": "Update package list",
  "command": "apt-get update"
}

TOML Format:

[[tasks]]
type = "command"
description = "Update package list"
command = "apt-get update"

Run command with specific working directory:

YAML Format:

- type: command
  description: "Build application in project directory"
  command: make build
  cwd: /opt/myapp

JSON Format:

{
  "type": "command",
  "description": "Build application in project directory",
  "command": "make build",
  "cwd": "/opt/myapp"
}

TOML Format:

[[tasks]]
type = "command"
description = "Build application in project directory"
command = "make build"
cwd = "/opt/myapp"

Run command as specific user:

YAML Format:

- type: command
  description: "Restart nginx service"
  command: systemctl restart nginx
  user: root

JSON Format:

{
  "type": "command",
  "description": "Restart nginx service",
  "command": "systemctl restart nginx",
  "user": "root"
}

TOML Format:

[[tasks]]
type = "command"
description = "Restart nginx service"
command = "systemctl restart nginx"
user = "root"

Register command output:

YAML Format:

- type: command
  description: "Check system uptime"
  command: uptime
  register: uptime_result
- type: debug
  msg: "The system uptime is: {{ uptime_result.stdout }}"

JSON Format:

[
  {
    "type": "command",
    "description": "Check system uptime",
    "command": "uptime",
    "register": "uptime_result"
  },
  {
    "type": "debug",
    "msg": "The system uptime is: {{ uptime_result.stdout }}"
  }
]

TOML Format:

[[tasks]]
type = "command"
description = "Check system uptime"
command = "uptime"
register = "uptime_result"
[[tasks]]
type = "debug"
msg = "The system uptime is: {{ uptime_result.stdout }}"

Idempotent command:

YAML Format:

- type: command
  description: "Initialize database (idempotent)"
  command: /opt/myapp/init-db.sh
  idempotent: true
  exit_code: 0

JSON Format:

{
  "type": "command",
  "description": "Initialize database (idempotent)",
  "command": "/opt/myapp/init-db.sh",
  "idempotent": true,
  "exit_code": 0
}

TOML Format:

[[tasks]]
type = "command"
description = "Initialize database (idempotent)"
command = "/opt/myapp/init-db.sh"
idempotent = true
exit_code = 0

raw

Description: Execute commands without shell processing task

Required Fields:

args (Vec): Command arguments (argv[1..])
creates (bool): Whether the command creates resources. When enabled with creates_files, the command will be skipped if any of the specified files/directories already exist (idempotency check).
creates_files (Vec): Files/directories created by the command. Used with creates flag for idempotency - if any listed file/directory already exists, the command is skipped.
environment (HashMap<String, String>): Environment variables
executable (String): Command to execute (argv[0])
exit_codes (Vec): Expected exit codes (defaults to [0])
force (bool): Force command execution
ignore_errors (bool): Whether to ignore errors
removes (bool): Whether the command removes resources. When enabled with removes_files, the command will be skipped if any of the specified files/directories don’t exist (idempotency check).
removes_files (Vec): Files/directories removed by the command. Used with removes flag for idempotency - if any listed file/directory doesn’t exist, the command is skipped.

Optional Fields:

chdir (Option): Working directory for command execution
description (Option): Optional description of what this task does

Human-readable description of the task’s purpose. Used for documentation and can be displayed in logs or reports.
timeout (Option): Execution timeout in seconds
when (Option): Optional condition to determine if the task should run

Examples:

Execute a simple command:

YAML Format:

- type: raw
  description: "List directory contents"
  executable: ls
  args: ["-la", "/tmp"]

JSON Format:

{
  "type": "raw",
  "description": "List directory contents",
  "executable": "ls",
  "args": ["-la", "/tmp"]
}

TOML Format:

[[tasks]]
type = "raw"
description = "List directory contents"
executable = "ls"
args = ["-la", "/tmp"]

Execute command with environment variables:

YAML Format:

- type: raw
  description: "Run command with environment"
  executable: /usr/local/bin/myapp
  args: ["--config", "/etc/myapp/config.json"]
  environment:
    DATABASE_URL: "postgresql://localhost/mydb"
    LOG_LEVEL: "debug"

JSON Format:

{
  "type": "raw",
  "description": "Run command with environment",
  "executable": "/usr/local/bin/myapp",
  "args": ["--config", "/etc/myapp/config.json"],
  "environment": {
    "DATABASE_URL": "postgresql://localhost/mydb",
    "LOG_LEVEL": "debug"
  }
}

TOML Format:

[[tasks]]
type = "raw"
description = "Run command with environment"
executable = "/usr/local/bin/myapp"
args = ["--config", "/etc/myapp/config.json"]
environment = { DATABASE_URL = "postgresql://localhost/mydb", LOG_LEVEL = "debug" }

Execute command with timeout:

YAML Format:

- type: raw
  description: "Run command with timeout"
  executable: sleep
  args: ["30"]
  timeout: 10
  ignore_errors: true

JSON Format:

{
  "type": "raw",
  "description": "Run command with timeout",
  "executable": "sleep",
  "args": ["30"],
  "timeout": 10,
  "ignore_errors": true
}

TOML Format:

[[tasks]]
type = "raw"
description = "Run command with timeout"
executable = "sleep"
args = ["30"]
timeout = 10
ignore_errors = true

Execute command in specific directory:

YAML Format:

- type: raw
  description: "Run command in project directory"
  executable: make
  args: ["build"]
  chdir: /opt/myproject

JSON Format:

{
  "type": "raw",
  "description": "Run command in project directory",
  "executable": "make",
  "args": ["build"],
  "chdir": "/opt/myproject"
}

TOML Format:

[[tasks]]
type = "raw"
description = "Run command in project directory"
executable = "make"
args = ["build"]
chdir = "/opt/myproject"

Execute command with creates/removes checks:

YAML Format:

- type: raw
  description: "Create configuration file"
  executable: touch
  args: ["/etc/myapp/config.conf"]
  creates: true
  creates_files: ["/etc/myapp/config.conf"]

JSON Format:

{
  "type": "raw",
  "description": "Create configuration file",
  "executable": "touch",
  "args": ["/etc/myapp/config.conf"],
  "creates": true,
  "creates_files": ["/etc/myapp/config.conf"]
}

TOML Format:

[[tasks]]
type = "raw"
description = "Create configuration file"
executable = "touch"
args = ["/etc/myapp/config.conf"]
creates = true
creates_files = ["/etc/myapp/config.conf"]

Execute command that removes files (idempotent):

YAML Format:

- type: raw
  description: "Remove temporary files"
  executable: rm
  args: ["-f", "/tmp/cache.dat"]
  removes: true
  removes_files: ["/tmp/cache.dat"]

JSON Format:

{
  "type": "raw",
  "description": "Remove temporary files",
  "executable": "rm",
  "args": ["-f", "/tmp/cache.dat"],
  "removes": true,
  "removes_files": ["/tmp/cache.dat"]
}

TOML Format:

[[tasks]]
type = "raw"
description = "Remove temporary files"
executable = "rm"
args = ["-f", "/tmp/cache.dat"]
removes = true
removes_files = ["/tmp/cache.dat"]

script

Description: Execute local scripts task

Required Fields:

creates (bool): Whether the script creates resources
creates_files (Vec): Files/directories created by the script (for creates check)
environment (HashMap<String, String>): Environment variables
force (bool): Force script execution
params (Vec): Script parameters/arguments
path (String): Path to the script file
removes (bool): Whether the script removes resources
removes_files (Vec): Files/directories removed by the script (for removes check)

Optional Fields:

chdir (Option): Working directory for script execution
description (Option): Optional description of what this task does

Human-readable description of the task’s purpose. Used for documentation and can be displayed in logs or reports.
timeout (Option): Execution timeout in seconds
when (Option): Optional condition to determine if the task should run

Examples:

Execute a script:

YAML Format:

- type: script
  description: "Run setup script"
  path: /usr/local/bin/setup.sh

JSON Format:

{
  "type": "script",
  "description": "Run setup script",
  "path": "/usr/local/bin/setup.sh"
}

TOML Format:

[[tasks]]
type = "script"
description = "Run setup script"
path = "/usr/local/bin/setup.sh"

Execute script with parameters:

YAML Format:

- type: script
  description: "Run deployment script with environment"
  path: /opt/deploy/deploy.sh
  params: ["production", "--verbose"]
  chdir: /opt/deploy

JSON Format:

{
  "type": "script",
  "description": "Run deployment script with environment",
  "path": "/opt/deploy/deploy.sh",
  "params": ["production", "--verbose"],
  "chdir": "/opt/deploy"
}

TOML Format:

[[tasks]]
type = "script"
description = "Run deployment script with environment"
path = "/opt/deploy/deploy.sh"
params = ["production", "--verbose"]
chdir = "/opt/deploy"

Execute script with environment variables:

YAML Format:

- type: script
  description: "Run script with environment"
  path: /usr/local/bin/configure.sh
  environment:
    DATABASE_URL: "postgresql://localhost/mydb"
    API_KEY: "secret-key"
  timeout: 300

JSON Format:

{
  "type": "script",
  "description": "Run script with environment",
  "path": "/usr/local/bin/configure.sh",
  "environment": {
    "DATABASE_URL": "postgresql://localhost/mydb",
    "API_KEY": "secret-key"
  },
  "timeout": 300
}

TOML Format:

[[tasks]]
type = "script"
description = "Run script with environment"
path = "/usr/local/bin/configure.sh"
environment = { DATABASE_URL = "postgresql://localhost/mydb", API_KEY = "secret-key" }
timeout = 300

Execute script with creates/removes checks:

YAML Format:

- type: script
  description: "Run initialization script"
  path: /usr/local/bin/init.sh
  creates: true
  timeout: 600

JSON Format:

{
  "type": "script",
  "description": "Run initialization script",
  "path": "/usr/local/bin/init.sh",
  "creates": true,
  "timeout": 600
}

TOML Format:

[[tasks]]
type = "script"
description = "Run initialization script"
path = "/usr/local/bin/init.sh"
creates = true
timeout = 600

File Operations

blockinfile

Description: Insert/update multi-line blocks task

Required Fields:

backup (bool): Backup file before modification
block (String): Block content (multi-line)
create (bool): Create file if it doesn’t exist
marker (String): Marker for block boundaries
path (String): Path to the file
state (BlockInFileState): Block state

Optional Fields:

description (Option): Optional description of what this task does

Human-readable description of the task’s purpose. Used for documentation and can be displayed in logs or reports.
insertafter (Option): Insert after this line (regex)
insertbefore (Option): Insert before this line (regex)
when (Option): Optional condition to determine if the task should run

Examples:

Insert a configuration block:

YAML Format:

- type: blockinfile
  description: "Add custom configuration block"
  path: /etc/myapp/config.conf
  state: present
  block: |
    # Custom configuration
    custom_option = true
    custom_value = 42
  marker: "# {mark} Custom Config"

JSON Format:

{
  "type": "blockinfile",
  "description": "Add custom configuration block",
  "path": "/etc/myapp/config.conf",
  "state": "present",
  "block": "# Custom configuration\ncustom_option = true\ncustom_value = 42\n",
  "marker": "# {mark} Custom Config"
}

TOML Format:

[[tasks]]
type = "blockinfile"
description = "Add custom configuration block"
path = "/etc/myapp/config.conf"
state = "present"
block = """
# Custom configuration
custom_option = true
custom_value = 42
"""
marker = "# {mark} Custom Config"

Insert block after specific content:

YAML Format:

- type: blockinfile
  description: "Add SSL configuration"
  path: /etc/httpd/httpd.conf
  state: present
  block: |
    SSLEngine on
    SSLCertificateFile /etc/ssl/certs/server.crt
    SSLCertificateKeyFile /etc/ssl/private/server.key
  insertafter: "^# LoadModule ssl_module"
  marker: "# {mark} SSL Config"

JSON Format:

{
  "type": "blockinfile",
  "description": "Add SSL configuration",
  "path": "/etc/httpd/httpd.conf",
  "state": "present",
  "block": "SSLEngine on\nSSLCertificateFile /etc/ssl/certs/server.crt\nSSLCertificateKeyFile /etc/ssl/private/server.key\n",
  "insertafter": "^# LoadModule ssl_module",
  "marker": "# {mark} SSL Config"
}

TOML Format:

[[tasks]]
type = "blockinfile"
description = "Add SSL configuration"
path = "/etc/httpd/httpd.conf"
state = "present"
block = """
SSLEngine on
SSLCertificateFile /etc/ssl/certs/server.crt
SSLCertificateKeyFile /etc/ssl/private/server.key
"""
insertafter = "^# LoadModule ssl_module"
marker = "# {mark} SSL Config"

Insert block with backup:

YAML Format:

- type: blockinfile
  description: "Add firewall rules with backup"
  path: /etc/iptables/rules.v4
  state: present
  block: |
    -A INPUT -p tcp --dport 80 -j ACCEPT
    -A INPUT -p tcp --dport 443 -j ACCEPT
  marker: "# {mark} Web Rules"
  backup: true

JSON Format:

{
  "type": "blockinfile",
  "description": "Add firewall rules with backup",
  "path": "/etc/iptables/rules.v4",
  "state": "present",
  "block": "-A INPUT -p tcp --dport 80 -j ACCEPT\n-A INPUT -p tcp --dport 443 -j ACCEPT\n",
  "marker": "# {mark} Web Rules",
  "backup": true
}

TOML Format:

[[tasks]]
type = "blockinfile"
description = "Add firewall rules with backup"
path = "/etc/iptables/rules.v4"
state = "present"
block = """
-A INPUT -p tcp --dport 80 -j ACCEPT
-A INPUT -p tcp --dport 443 -j ACCEPT
"""
marker = "# {mark} Web Rules"
backup = true

Remove a configuration block:

YAML Format:

- type: blockinfile
  description: "Remove old configuration"
  path: /etc/myapp/config.conf
  state: absent
  marker: "# {mark} Old Config"

JSON Format:

{
  "type": "blockinfile",
  "description": "Remove old configuration",
  "path": "/etc/myapp/config.conf",
  "state": "absent",
  "marker": "# {mark} Old Config"
}

TOML Format:

[[tasks]]
type = "blockinfile"
description = "Remove old configuration"
path = "/etc/myapp/config.conf"
state = "absent"
marker = "# {mark} Old Config"

copy

Description: Copy files task

Required Fields:

backup (bool): Whether to create backup of destination
dest (String): Destination file path
follow (bool): Whether to follow symlinks
force (bool): Force copy even if destination exists
mode (bool): Whether to preserve permissions
owner (bool): Whether to preserve ownership
src (String): Source file path
state (CopyState): Copy state
timestamp (bool): Whether to preserve timestamps

Optional Fields:

description (Option): Optional description of what this task does

Human-readable description of the task’s purpose. Used for documentation and can be displayed in logs or reports.
when (Option): Optional condition to determine if the task should run

Examples:

Copy a file:

YAML Format:

- type: copy
  description: "Copy configuration file"
  src: /etc/nginx/nginx.conf.template
  dest: /etc/nginx/nginx.conf
  state: present

JSON Format:

{
  "type": "copy",
  "description": "Copy configuration file",
  "src": "/etc/nginx/nginx.conf.template",
  "dest": "/etc/nginx/nginx.conf",
  "state": "present"
}

TOML Format:

[[tasks]]
type = "copy"
description = "Copy configuration file"
src = "/etc/nginx/nginx.conf.template"
dest = "/etc/nginx/nginx.conf"
state = "present"

Copy with backup:

YAML Format:

- type: copy
  description: "Copy config with backup"
  src: /tmp/new-config.conf
  dest: /etc/myapp/config.conf
  state: present
  backup: true

JSON Format:

{
  "type": "copy",
  "description": "Copy config with backup",
  "src": "/tmp/new-config.conf",
  "dest": "/etc/myapp/config.conf",
  "state": "present",
  "backup": true
}

TOML Format:

[[tasks]]
type = "copy"
description = "Copy config with backup"
src = "/tmp/new-config.conf"
dest = "/etc/myapp/config.conf"
state = "present"
backup = true

Remove a copied file:

YAML Format:

- type: copy
  description: "Remove copied configuration"
  src: /etc/nginx/nginx.conf.template
  dest: /etc/nginx/nginx.conf
  state: absent

JSON Format:

{
  "type": "copy",
  "description": "Remove copied configuration",
  "src": "/etc/nginx/nginx.conf.template",
  "dest": "/etc/nginx/nginx.conf",
  "state": "absent"
}

TOML Format:

[[tasks]]
type = "copy"
description = "Remove copied configuration"
src = "/etc/nginx/nginx.conf.template"
dest = "/etc/nginx/nginx.conf"
state = "absent"

fetch

Description: Fetch files from remote hosts task

Required Fields:

dest (String): Destination file path
follow_redirects (bool): Follow redirects
force (bool): Force download even if file exists
headers (HashMap<String, String>): HTTP headers
state (FetchState): Fetch state
timeout (u64): Timeout in seconds
url (String): Source URL
validate_certs (bool): Validate SSL certificates

Optional Fields:

description (Option): Optional description of what this task does

Human-readable description of the task’s purpose. Used for documentation and can be displayed in logs or reports.
password (Option): Password for basic auth
username (Option): Username for basic auth
when (Option): Optional condition to determine if the task should run

Examples:

Download a file:

YAML Format:

- type: fetch
  description: "Download configuration file"
  url: http://example.com/config.yml
  dest: /etc/myapp/config.yml
  state: present

JSON Format:

{
  "type": "fetch",
  "description": "Download configuration file",
  "url": "http://example.com/config.yml",
  "dest": "/etc/myapp/config.yml",
  "state": "present"
}

TOML Format:

[[tasks]]
type = "fetch"
description = "Download configuration file"
url = "http://example.com/config.yml"
dest = "/etc/myapp/config.yml"
state = "present"

Download with authentication:

YAML Format:

- type: fetch
  description: "Download private file"
  url: https://private.example.com/file.txt
  dest: /tmp/private.txt
  state: present
  username: myuser
  password: mypassword

JSON Format:

{
  "type": "fetch",
  "description": "Download private file",
  "url": "https://private.example.com/file.txt",
  "dest": "/tmp/private.txt",
  "state": "present",
  "username": "myuser",
  "password": "mypassword"
}

TOML Format:

[[tasks]]
type = "fetch"
description = "Download private file"
url = "https://private.example.com/file.txt"
dest = "/tmp/private.txt"
state = "present"
username = "myuser"
password = "mypassword"

Download with custom headers:

YAML Format:

- type: fetch
  description: "Download with custom headers"
  url: https://api.example.com/data.json
  dest: /tmp/data.json
  state: present
  headers:
    Authorization: "Bearer token123"
    X-API-Key: "apikey456"

JSON Format:

{
  "type": "fetch",
  "description": "Download with custom headers",
  "url": "https://api.example.com/data.json",
  "dest": "/tmp/data.json",
  "state": "present",
  "headers": {
    "Authorization": "Bearer token123",
    "X-API-Key": "apikey456"
  }
}

TOML Format:

[[tasks]]
type = "fetch"
description = "Download with custom headers"
url = "https://api.example.com/data.json"
dest = "/tmp/data.json"
state = "present"
headers = { Authorization = "Bearer token123", "X-API-Key" = "apikey456" }

Force download:

YAML Format:

- type: fetch
  description: "Force download latest version"
  url: https://example.com/latest.tar.gz
  dest: /tmp/latest.tar.gz
  state: present
  force: true

JSON Format:

{
  "type": "fetch",
  "description": "Force download latest version",
  "url": "https://example.com/latest.tar.gz",
  "dest": "/tmp/latest.tar.gz",
  "state": "present",
  "force": true
}

TOML Format:

[[tasks]]
type = "fetch"
description = "Force download latest version"
url = "https://example.com/latest.tar.gz"
dest = "/tmp/latest.tar.gz"
state = "present"
force = true

file

Description: File operation task

Manages files and directories - create, modify, or remove files with content, permissions, and ownership. Similar to Ansible’s file module.

Required Fields:

path (String): Path to the file or directory

Absolute path to the file or directory to manage. Parent directories will not be created automatically.
state (FileState): File state (present, absent)
- present: Ensure the file exists with specified properties
- absent: Ensure the file does not exist

Optional Fields:

content (Option): File content (for present state)

Content to write to the file when state is present. Mutually exclusive with source.
description (Option): Optional description of what this task does

Human-readable description of the task’s purpose. Used for documentation and can be displayed in logs or reports.
group (Option): File group name

Group name for the file. Only applied when creating or modifying files.
mode (Option): File permissions (octal string like “0644”)

File permissions in octal notation (e.g., “0644”, “0755”). Only applied when creating or modifying files.
owner (Option): File owner username

Username of the file owner. Only applied when creating or modifying files.
source (Option): Source file to copy from (alternative to content)

Path to a source file to copy content from when state is present. Mutually exclusive with content.
when (Option): Optional condition to determine if the task should run

Examples:

Create a file with content:

YAML Format:

- type: file
  description: "Create nginx configuration file"
  path: /etc/nginx/sites-available/default
  state: present
  content: |
    server {
        listen 80;
        root /var/www/html;
        index index.html index.htm;
        location / {
            try_files $uri $uri/ =404;
        }
    }
  mode: "0644"
  owner: root
  group: root

JSON Format:

{
  "type": "file",
  "description": "Create nginx configuration file",
  "path": "/etc/nginx/sites-available/default",
  "state": "present",
  "content": "server {\n    listen 80;\n    root /var/www/html;\n    index index.html index.htm;\n\n    location / {\n        try_files $uri $uri/ =404;\n    }\n}",
  "mode": "0644",
  "owner": "root",
  "group": "root"
}

TOML Format:

[[tasks]]
type = "file"
description = "Create nginx configuration file"
path = "/etc/nginx/sites-available/default"
state = "present"
content = """
server {
    listen 80;
    root /var/www/html;
    index index.html index.htm;
    location / {
        try_files $uri $uri/ =404;
    }
}
"""
mode = "0644"
owner = "root"
group = "root"

Register file creation:

YAML Format:

- type: file
  description: "Create marker file"
  path: /tmp/driftless.marker
  state: present
  register: marker_file

JSON Format:

{
  "type": "file",
  "description": "Create marker file",
  "path": "/tmp/driftless.marker",
  "state": "present",
  "register": "marker_file"
}

TOML Format:

[[tasks]]
type = "file"
description = "Create marker file"
path = "/tmp/driftless.marker"
state = "present"
register = "marker_file"

lineinfile

Description: Ensure line in file task

Required Fields:

backup (bool): Backup file before modification
create (bool): Create file if it doesn’t exist
line (String): The line content
path (String): Path to the file
state (LineInFileState): Line state

Optional Fields:

description (Option): Optional description of what this task does

Human-readable description of the task’s purpose. Used for documentation and can be displayed in logs or reports.
insertafter (Option): Insert after this line (regex)
insertbefore (Option): Insert before this line (regex)
regexp (Option): Regular expression to match existing line
when (Option): Optional condition to determine if the task should run

Examples:

Add a line to a file:

YAML Format:

- type: lineinfile
  description: "Add localhost entry to hosts file"
  path: /etc/hosts
  state: present
  line: "127.0.0.1 localhost"

JSON Format:

{
  "type": "lineinfile",
  "description": "Add localhost entry to hosts file",
  "path": "/etc/hosts",
  "state": "present",
  "line": "127.0.0.1 localhost"
}

TOML Format:

[[tasks]]
type = "lineinfile"
description = "Add localhost entry to hosts file"
path = "/etc/hosts"
state = "present"
line = "127.0.0.1 localhost"

Replace a line using regex:

YAML Format:

- type: lineinfile
  description: "Update SSH port configuration"
  path: /etc/ssh/sshd_config
  state: present
  regexp: "^#?Port .*"
  line: "Port 22"

JSON Format:

{
  "type": "lineinfile",
  "description": "Update SSH port configuration",
  "path": "/etc/ssh/sshd_config",
  "state": "present",
  "regexp": "^#?Port .*",
  "line": "Port 22"
}

TOML Format:

[[tasks]]
type = "lineinfile"
description = "Update SSH port configuration"
path = "/etc/ssh/sshd_config"
state = "present"
regexp = "^#?Port .*"
line = "Port 22"

Insert line after a pattern:

YAML Format:

- type: lineinfile
  description: "Add include directive after main config"
  path: /etc/nginx/nginx.conf
  state: present
  line: "include /etc/nginx/sites-enabled/*;"
  insertafter: "http \{"

JSON Format:

{
  "type": "lineinfile",
  "description": "Add include directive after main config",
  "path": "/etc/nginx/nginx.conf",
  "state": "present",
  "line": "include /etc/nginx/sites-enabled/*;",
  "insertafter": "http \{"
}

TOML Format:

[[tasks]]
type = "lineinfile"
description = "Add include directive after main config"
path = "/etc/nginx/nginx.conf"
state = "present"
line = "include /etc/nginx/sites-enabled/*;"
insertafter = "http \{"

replace

Description: Replace text in files task

Required Fields:

backup (bool): Backup file before modification
path (String): Path to the file
replace (String): Replacement string
replace_all (bool): Replace all occurrences
state (ReplaceState): Replace state

Optional Fields:

before (Option): String to match (alternative to regexp)
description (Option): Optional description of what this task does

Human-readable description of the task’s purpose. Used for documentation and can be displayed in logs or reports.
regexp (Option): Regular expression to match
when (Option): Optional condition to determine if the task should run

Examples:

Replace text using regex:

YAML Format:

- type: replace
  description: "Update database host"
  path: /etc/myapp/config.ini
  state: present
  regexp: '^db_host\s*=\s*.*$'
  replace: 'db_host = newdb.example.com'

JSON Format:

{
  "type": "replace",
  "description": "Update database host",
  "path": "/etc/myapp/config.ini",
  "state": "present",
  "regexp": "^db_host\\s*=\\s*.*$",
  "replace": "db_host = newdb.example.com"
}

TOML Format:

[[tasks]]
type = "replace"
description = "Update database host"
path = "/etc/myapp/config.ini"
state = "present"
regexp = "^db_host\\s*=\\s*.*$"
replace = "db_host = newdb.example.com"

Replace string literal:

YAML Format:

- type: replace
  description: "Update version number"
  path: /opt/myapp/version.txt
  state: present
  before: 'version = "1.0.0"'
  replace: 'version = "1.1.0"'

JSON Format:

{
  "type": "replace",
  "description": "Update version number",
  "path": "/opt/myapp/version.txt",
  "state": "present",
  "before": "version = \"1.0.0\"",
  "replace": "version = \"1.1.0\""
}

TOML Format:

[[tasks]]
type = "replace"
description = "Update version number"
path = "/opt/myapp/version.txt"
state = "present"
before = 'version = "1.0.0"'
replace = 'version = "1.1.0"'

Replace with backup:

YAML Format:

- type: replace
  description: "Update configuration with backup"
  path: /etc/httpd/httpd.conf
  state: present
  regexp: '^Listen 80$'
  replace: 'Listen 8080'
  backup: true

JSON Format:

{
  "type": "replace",
  "description": "Update configuration with backup",
  "path": "/etc/httpd/httpd.conf",
  "state": "present",
  "regexp": "^Listen 80$",
  "replace": "Listen 8080",
  "backup": true
}

TOML Format:

[[tasks]]
type = "replace"
description = "Update configuration with backup"
path = "/etc/httpd/httpd.conf"
state = "present"
regexp = "^Listen 80$"
replace = "Listen 8080"
backup = true

Replace all occurrences:

YAML Format:

- type: replace
  description: "Update all IP addresses"
  path: /etc/hosts
  state: present
  regexp: '192\.168\.1\.\d+'
  replace: '10.0.0.100'
  replace_all: true

JSON Format:

{
  "type": "replace",
  "description": "Update all IP addresses",
  "path": "/etc/hosts",
  "state": "present",
  "regexp": "192\\.168\\.1\\.\\d+",
  "replace": "10.0.0.100",
  "replace_all": true
}

TOML Format:

[[tasks]]
type = "replace"
description = "Update all IP addresses"
path = "/etc/hosts"
state = "present"
regexp = "192\\.168\\.1\\.\\d+"
replace = "10.0.0.100"
replace_all = true

stat

Description: File/directory statistics task

Required Fields:

checksum (bool): Get checksum of file
checksum_algorithm (ChecksumAlgorithm): Checksum algorithm
follow (bool): Whether to follow symlinks
path (String): Path to check

Optional Fields:

description (Option): Optional description of what this task does

Human-readable description of the task’s purpose. Used for documentation and can be displayed in logs or reports.
register (Option): Optional variable name to register the task result in
when (Option): Optional condition to determine if the task should run

Registered Outputs:

checksum (String): The file checksum (if checksum is true)
exists (bool): Whether the file or directory exists
gid (u32): The group ID of the owner
is_dir (bool): Whether the path is a directory
is_file (bool): Whether the path is a file
mode (u32): The file mode (permissions)
modified (u64): Last modification time (epoch seconds)
size (u64): The size of the file in bytes
uid (u32): The user ID of the owner

Examples:

Get file statistics:

YAML Format:

- type: stat
  description: "Get file statistics"
  path: /etc/passwd

JSON Format:

{
  "type": "stat",
  "description": "Get file statistics",
  "path": "/etc/passwd"
}

TOML Format:

[[tasks]]
type = "stat"
description = "Get file statistics"
path = "/etc/passwd"

Get file checksum:

YAML Format:

- type: stat
  description: "Get file checksum"
  path: /etc/hosts
  checksum: true
  checksum_algorithm: sha256

JSON Format:

{
  "type": "stat",
  "description": "Get file checksum",
  "path": "/etc/hosts",
  "checksum": true,
  "checksum_algorithm": "sha256"
}

TOML Format:

[[tasks]]
type = "stat"
description = "Get file checksum"
path = "/etc/hosts"
checksum = true
checksum_algorithm = "sha256"

Follow symlinks:

YAML Format:

- type: stat
  description: "Follow symlink for statistics"
  path: /var/log/syslog
  follow: true

JSON Format:

{
  "type": "stat",
  "description": "Follow symlink for statistics",
  "path": "/var/log/syslog",
  "follow": true
}

TOML Format:

[[tasks]]
type = "stat"
description = "Follow symlink for statistics"
path = "/var/log/syslog"
follow = true

Register file status:

YAML Format:

- type: stat
  description: "Check if nginx config exists"
  path: /etc/nginx/nginx.conf
  register: nginx_conf
- type: debug
  msg: "Nginx config exists: {{ nginx_conf.exists }}"
  when: "{{ nginx_conf.exists }}"

JSON Format:

[
  {
    "type": "stat",
    "description": "Check if nginx config exists",
    "path": "/etc/nginx/nginx.conf",
    "register": "nginx_conf"
  },
  {
    "type": "debug",
    "msg": "Nginx config exists: {{ nginx_conf.exists }}",
    "when": "{{ nginx_conf.exists }}"
  }
]

TOML Format:

[[tasks]]
type = "stat"
description = "Check if nginx config exists"
path = "/etc/nginx/nginx.conf"
register = "nginx_conf"
[[tasks]]
type = "debug"
msg = "Nginx config exists: {{ nginx_conf.exists }}"
when = "{{ nginx_conf.exists }}"

Get directory statistics:

YAML Format:

- type: stat
  description: "Get directory statistics"
  path: /home/user

JSON Format:

{
  "type": "stat",
  "description": "Get directory statistics",
  "path": "/home/user"
}

TOML Format:

[[tasks]]
type = "stat"
description = "Get directory statistics"
path = "/home/user"

template

Description: Template rendering task

Required Fields:

backup (bool): Backup destination before templating
dest (String): Destination file
force (bool): Force template rendering
src (String): Source template file
state (TemplateState): Template state
vars (HashMap<String, Value>): Variables for template rendering

Optional Fields:

description (Option): Optional description of what this task does

Human-readable description of the task’s purpose. Used for documentation and can be displayed in logs or reports.
template_dir (Option): Template directory for includes/imports

Directory containing templates that can be included or imported. If not specified, includes/imports will not work.
when (Option): Optional condition to determine if the task should run

Examples:

Render a template:

YAML Format:

- type: template
  description: "Render nginx configuration"
  src: /templates/nginx.conf.j2
  dest: /etc/nginx/sites-available/default
  state: present
  vars:
    server_name: example.com
    port: 80
    root_dir: /var/www/html

JSON Format:

{
  "type": "template",
  "description": "Render nginx configuration",
  "src": "/templates/nginx.conf.j2",
  "dest": "/etc/nginx/sites-available/default",
  "state": "present",
  "vars": {
    "server_name": "example.com",
    "port": 80,
    "root_dir": "/var/www/html"
  }
}

TOML Format:

[[tasks]]
type = "template"
description = "Render nginx configuration"
src = "/templates/nginx.conf.j2"
dest = "/etc/nginx/sites-available/default"
state = "present"
[tasks.vars]
server_name = "example.com"
port = 80
root_dir = "/var/www/html"

Render template with backup:

YAML Format:

- type: template
  description: "Update config with backup"
  src: /templates/app.conf.j2
  dest: /etc/myapp/config.conf
  state: present
  backup: true
  vars:
    database_host: localhost
    database_port: 5432

JSON Format:

{
  "type": "template",
  "description": "Update config with backup",
  "src": "/templates/app.conf.j2",
  "dest": "/etc/myapp/config.conf",
  "state": "present",
  "backup": true,
  "vars": {
    "database_host": "localhost",
    "database_port": 5432
  }
}

TOML Format:

[[tasks]]
type = "template"
description = "Update config with backup"
src = "/templates/app.conf.j2"
dest = "/etc/myapp/config.conf"
state = "present"
backup = true
[tasks.vars]
database_host = "localhost"
database_port = 5432

Remove rendered template:

YAML Format:

- type: template
  description: "Remove rendered configuration"
  src: /templates/old.conf.j2
  dest: /etc/oldapp/config.conf
  state: absent

JSON Format:

{
  "type": "template",
  "description": "Remove rendered configuration",
  "src": "/templates/old.conf.j2",
  "dest": "/etc/oldapp/config.conf",
  "state": "absent"
}

TOML Format:

[[tasks]]
type = "template"
description = "Remove rendered configuration"
src = "/templates/old.conf.j2"
dest = "/etc/oldapp/config.conf"
state = "absent"

unarchive

Description: Unarchive files task

Required Fields:

creates (bool): Whether to create destination directory
dest (String): Destination directory
extra_opts (Vec): Extra options for extraction
follow_redirects (bool): Follow redirects for URL downloads
headers (HashMap<String, String>): HTTP headers for URL downloads
keep_original (bool): Whether to keep the archive after extraction
list_files (Vec): List of files to extract (empty = all)
src (String): Source archive file (local path) or URL
state (UnarchiveState): Unarchive state
timeout (u64): Timeout for URL downloads
validate_certs (bool): Validate SSL certificates for URL downloads

Optional Fields:

description (Option): Optional description of what this task does

Human-readable description of the task’s purpose. Used for documentation and can be displayed in logs or reports.
format (Option): Archive format (auto-detect if not specified)
password (Option): Password for basic auth for URL downloads
username (Option): Username for basic auth for URL downloads
when (Option): Optional condition to determine if the task should run

Examples:

Extract a tar archive:

YAML Format:

- type: unarchive
  description: "Extract application archive"
  src: /tmp/myapp.tar.gz
  dest: /opt/myapp
  state: present

JSON Format:

{
  "type": "unarchive",
  "description": "Extract application archive",
  "src": "/tmp/myapp.tar.gz",
  "dest": "/opt/myapp",
  "state": "present"
}

TOML Format:

[[tasks]]
type = "unarchive"
description = "Extract application archive"
src = "/tmp/myapp.tar.gz"
dest = "/opt/myapp"
state = "present"

Extract from URL:

YAML Format:

- type: unarchive
  description: "Download and extract software"
  src: https://example.com/software.tar.gz
  dest: /opt/software
  state: present
  creates: true

JSON Format:

{
  "type": "unarchive",
  "description": "Download and extract software",
  "src": "https://example.com/software.tar.gz",
  "dest": "/opt/software",
  "state": "present",
  "creates": true
}

TOML Format:

[[tasks]]
type = "unarchive"
description = "Download and extract software"
src = "https://example.com/software.tar.gz"
dest = "/opt/software"
state = "present"
creates = true

Extract specific files:

YAML Format:

- type: unarchive
  description: "Extract configuration files"
  src: /tmp/configs.tar.gz
  dest: /etc/myapp
  state: present
  list_files:
    - config.yml
    - settings.json

JSON Format:

{
  "type": "unarchive",
  "description": "Extract configuration files",
  "src": "/tmp/configs.tar.gz",
  "dest": "/etc/myapp",
  "state": "present",
  "list_files": ["config.yml", "settings.json"]
}

TOML Format:

[[tasks]]
type = "unarchive"
description = "Extract configuration files"
src = "/tmp/configs.tar.gz"
dest = "/etc/myapp"
state = "present"
list_files = ["config.yml", "settings.json"]

Extract zip archive:

YAML Format:

- type: unarchive
  description: "Extract zip archive"
  src: /tmp/data.zip
  dest: /var/data
  state: present
  format: zip

JSON Format:

{
  "type": "unarchive",
  "description": "Extract zip archive",
  "src": "/tmp/data.zip",
  "dest": "/var/data",
  "state": "present",
  "format": "zip"
}

TOML Format:

[[tasks]]
type = "unarchive"
description = "Extract zip archive"
src = "/tmp/data.zip"
dest = "/var/data"
state = "present"
format = "zip"

Monitoring & Logging

journald

Description: Journald configuration task

Manages systemd journal configuration. Can modify the main /etc/systemd/journald.conf file or create drop-in configuration files in /etc/systemd/journald.conf.d/. Supports all journald configuration options like storage settings, size limits, forwarding options, and compression settings.

Required Fields:

config (HashMap<String, String>): Journald configuration options

Key-value pairs of journald configuration options. Required when state is present. Common options include:
- Storage: volatile|persistent|auto|none
- SystemMaxUse: Maximum disk space to use
- SystemKeepFree: Disk space to keep free
- SystemMaxFileSize: Maximum size of individual journal files
- MaxRetentionSec: Maximum time to retain journal entries
- ForwardToSyslog: Forward to syslog
- Compress: Enable compression
state (JournaldState): Configuration state (present, absent)
- present: Ensure the journald configuration exists
- absent: Ensure the journald configuration does not exist

Optional Fields:

description (Option): Optional description of what this task does

Human-readable description of the task’s purpose. Used for documentation and can be displayed in logs or reports.
name (Option): Configuration name (for drop-in configs)

Name of the drop-in configuration file to create in /etc/systemd/journald.conf.d/. If not specified, modifies the main /etc/systemd/journald.conf file. This becomes the filename (e.g., “storage” creates /etc/systemd/journald.conf.d/storage.conf).
when (Option): Optional condition to determine if the task should run

Examples:

Configure journald storage and rotation:

YAML Format:

- type: journald
  description: "Configure systemd journal settings"
  config:
    Storage: persistent
    SystemMaxUse: 100M
    SystemKeepFree: 500M
    SystemMaxFileSize: 10M
    MaxRetentionSec: 1week
  state: present

JSON Format:

{
  "type": "journald",
  "description": "Configure systemd journal settings",
  "config": {
    "Storage": "persistent",
    "SystemMaxUse": "100M",
    "SystemKeepFree": "500M",
    "SystemMaxFileSize": "10M",
    "MaxRetentionSec": "1week"
  },
  "state": "present"
}

TOML Format:

[[tasks]]
type = "journald"
description = "Configure systemd journal settings"
[tasks.config]
Storage = "persistent"
SystemMaxUse = "100M"
SystemKeepFree = "500M"
SystemMaxFileSize = "10M"
MaxRetentionSec = "1week"
state = "present"

logrotate

Description: Logrotate configuration task

Manages logrotate configuration files in /etc/logrotate.d/. Creates or removes logrotate configuration snippets for log rotation management.

Required Fields:

name (String): Configuration name

Name of the logrotate configuration file to create in /etc/logrotate.d/. This becomes the filename (e.g., “nginx” creates /etc/logrotate.d/nginx).
options (Vec): Logrotate options

List of logrotate configuration options. Common options include:
- “daily”, “weekly”, “monthly”, “yearly”
- “rotate N” (keep N rotations)
- “compress”, “delaycompress”
- “missingok”, “notifempty”
- “create MODE OWNER GROUP”
state (LogrotateState): Configuration state (present, absent)
- present: Ensure the logrotate configuration exists
- absent: Ensure the logrotate configuration does not exist

Optional Fields:

description (Option): Optional description of what this task does

Human-readable description of the task’s purpose. Used for documentation and can be displayed in logs or reports.
path (Option): Log file path(s)

Path or glob pattern for log files to rotate. Required when state is present. Examples: “/var/log/app/*.log”, “/var/log/nginx/access.log”
postrotate (Option): Post-rotate script

Shell commands to execute after log rotation. Commonly used to reload services after log rotation.
when (Option): Optional condition to determine if the task should run

Examples:

Create a logrotate configuration for nginx:

YAML Format:

- type: logrotate
  description: "Configure nginx log rotation"
  name: nginx
  path: /var/log/nginx/*.log
  options:
    - weekly
    - rotate 52
    - compress
    - delaycompress
    - missingok
    - notifempty
    - create 644 www-data www-data
  postrotate: |
    systemctl reload nginx
  state: present

JSON Format:

{
  "type": "logrotate",
  "description": "Configure nginx log rotation",
  "name": "nginx",
  "path": "/var/log/nginx/*.log",
  "options": [
    "weekly",
    "rotate 52",
    "compress",
    "delaycompress",
    "missingok",
    "notifempty",
    "create 644 www-data www-data"
  ],
  "postrotate": "systemctl reload nginx\n",
  "state": "present"
}

TOML Format:

[[tasks]]
type = "logrotate"
description = "Configure nginx log rotation"
name = "nginx"
path = "/var/log/nginx/*.log"
options = [
  "weekly",
  "rotate 52",
  "compress",
  "delaycompress",
  "missingok",
  "notifempty",
  "create 644 www-data www-data"
]
postrotate = """
systemctl reload nginx
"""
state = "present"

rsyslog

Description: Rsyslog configuration task

Manages rsyslog configuration files in /etc/rsyslog.d/. Creates or removes rsyslog configuration snippets for log processing and forwarding.

Required Fields:

name (String): Configuration name

Name of the rsyslog configuration file to create in /etc/rsyslog.d/. This becomes the filename (e.g., “remote-logging” creates /etc/rsyslog.d/remote-logging.conf).
state (RsyslogState): Configuration state (present, absent)
- present: Ensure the rsyslog configuration exists
- absent: Ensure the rsyslog configuration does not exist

Optional Fields:

config (Option): Rsyslog configuration content

The rsyslog configuration directives. Required when state is present. Examples include log forwarding rules, custom log files, filters, etc.
description (Option): Optional description of what this task does

Human-readable description of the task’s purpose. Used for documentation and can be displayed in logs or reports.
when (Option): Optional condition to determine if the task should run

Examples:

Create an rsyslog configuration for remote logging:

YAML Format:

- type: rsyslog
  description: "Configure remote log forwarding"
  name: remote-logging
  config: |
    # Forward all logs to remote server
    *.* @@logserver.example.com:514
    # Forward auth logs with TCP
    auth.* @@logserver.example.com:514
  state: present

JSON Format:

{
  "type": "rsyslog",
  "description": "Configure remote log forwarding",
  "name": "remote-logging",
  "config": "*.* @@logserver.example.com:514\n\nauth.* @@logserver.example.com:514\n",
  "state": "present"
}

TOML Format:

[[tasks]]
type = "rsyslog"
description = "Configure remote log forwarding"
name = "remote-logging"
config = """
*.* @@logserver.example.com:514
auth.* @@logserver.example.com:514
"""
state = "present"

Network Operations

geturl

Description: Download files from HTTP/HTTPS/FTP task

Downloads files from web servers or FTP servers. Supports authentication, checksum validation, and file permission management. Similar to Ansible’s get_url module.

Required Fields:

backup (bool): Backup destination before download
dest (String): Destination file path
follow_redirects (bool): Follow redirects
force (bool): Force download even if file exists
headers (HashMap<String, String>): HTTP headers
state (GetUrlState): Get URL state
timeout (u64): Timeout in seconds
url (String): Source URL
validate_certs (bool): Validate SSL certificates

Optional Fields:

checksum (Option): Checksum validation
description (Option): Optional description of what this task does

Human-readable description of the task’s purpose. Used for documentation and can be displayed in logs or reports.
group (Option): File group
mode (Option): File permissions (octal string like “0644”)
owner (Option): File owner
password (Option): Password for basic auth
username (Option): Username for basic auth
when (Option): Optional condition to determine if the task should run

Examples:

Download a file:

YAML Format:

- type: get_url
  description: "Download configuration file"
  url: https://example.com/config.yml
  dest: /etc/myapp/config.yml
  state: present

JSON Format:

{
  "type": "get_url",
  "description": "Download configuration file",
  "url": "https://example.com/config.yml",
  "dest": "/etc/myapp/config.yml",
  "state": "present"
}

TOML Format:

[[tasks]]
type = "get_url"
description = "Download configuration file"
url = "https://example.com/config.yml"
dest = "/etc/myapp/config.yml"
state = "present"

Download with checksum validation:

YAML Format:

- type: get_url
  description: "Download software with checksum validation"
  url: https://example.com/software.tar.gz
  dest: /tmp/software.tar.gz
  state: present
  checksum: sha256:abc123def456...

JSON Format:

{
  "type": "get_url",
  "description": "Download software with checksum validation",
  "url": "https://example.com/software.tar.gz",
  "dest": "/tmp/software.tar.gz",
  "state": "present",
  "checksum": "sha256:abc123def456..."
}

TOML Format:

[[tasks]]
type = "get_url"
description = "Download software with checksum validation"
url = "https://example.com/software.tar.gz"
dest = "/tmp/software.tar.gz"
state = "present"
checksum = "sha256:abc123def456..."

Download with authentication:

YAML Format:

- type: get_url
  description: "Download private file"
  url: https://private.example.com/file.txt
  dest: /tmp/private.txt
  state: present
  username: myuser
  password: mypassword

JSON Format:

{
  "type": "get_url",
  "description": "Download private file",
  "url": "https://private.example.com/file.txt",
  "dest": "/tmp/private.txt",
  "state": "present",
  "username": "myuser",
  "password": "mypassword"
}

TOML Format:

[[tasks]]
type = "get_url"
description = "Download private file"
url = "https://private.example.com/file.txt"
dest = "/tmp/private.txt"
state = "present"
username = "myuser"
password = "mypassword"

Download and set permissions:

YAML Format:

- type: get_url
  description: "Download script with proper permissions"
  url: https://example.com/script.sh
  dest: /usr/local/bin/myscript.sh
  state: present
  mode: "0755"
  owner: root
  group: root

JSON Format:

{
  "type": "get_url",
  "description": "Download script with proper permissions",
  "url": "https://example.com/script.sh",
  "dest": "/usr/local/bin/myscript.sh",
  "state": "present",
  "mode": "0755",
  "owner": "root",
  "group": "root"
}

TOML Format:

[[tasks]]
type = "get_url"
description = "Download script with proper permissions"
url = "https://example.com/script.sh"
dest = "/usr/local/bin/myscript.sh"
state = "present"
mode = "0755"
owner = "root"
group = "root"

uri

Description: Interact with web services task

Makes HTTP requests to web services and APIs. Validates responses and can return content. Similar to Ansible’s uri module.

Required Fields:

follow_redirects (bool): Follow redirects
force (bool): Force execution even if idempotent
headers (HashMap<String, String>): HTTP headers
method (HttpMethod): HTTP method
return_content (bool): Return content in result
state (UriState): URI state
status_code (Vec): Expected status codes
timeout (u64): Timeout in seconds
url (String): Target URL
validate_certs (bool): Validate SSL certificates

Optional Fields:

body (Option): Request body
content_type (Option): Content type for request body
description (Option): Optional description of what this task does

Human-readable description of the task’s purpose. Used for documentation and can be displayed in logs or reports.
password (Option): Password for basic auth
register (Option): Optional variable name to register the task result in
username (Option): Username for basic auth
when (Option): Optional condition to determine if the task should run

Registered Outputs:

changed (bool): Whether the request was successfully made
content (String): The body of the response (if return_content is true)
status (u16): The HTTP status code of the response

Examples:

Simple GET request:

YAML Format:

- type: uri
  description: "Check API health endpoint"
  url: https://api.example.com/health
  method: GET
  status_code: 200
  return_content: true

JSON Format:

{
  "type": "uri",
  "description": "Check API health endpoint",
  "url": "https://api.example.com/health",
  "method": "GET",
  "status_code": 200,
  "return_content": true
}

TOML Format:

[[tasks]]
type = "uri"
description = "Check API health endpoint"
url = "https://api.example.com/health"
method = "GET"
status_code = 200
return_content = true

POST request with JSON body:

YAML Format:

- type: uri
  description: "Create a new user via API"
  url: https://api.example.com/users
  method: POST
  body: "{\"name\": \"John Doe\", \"email\": \"john@example.com\"}"
  headers:
    Content-Type: application/json
  status_code: 201

JSON Format:

{
  "type": "uri",
  "description": "Create a new user via API",
  "url": "https://api.example.com/users",
  "method": "POST",
  "body": "{\"name\": \"John Doe\", \"email\": \"john@example.com\"}",
  "headers": {
    "Content-Type": "application/json"
  },
  "status_code": 201
}

TOML Format:

[[tasks]]
type = "uri"
description = "Create a new user via API"
url = "https://api.example.com/users"
method = "POST"
body = "{\"name\": \"John Doe\", \"email\": \"john@example.com\"}"
[tasks.headers]
Content-Type = "application/json"
[tasks]]
status_code = 201

Request with authentication:

YAML Format:

- type: uri
  description: "Get user profile with authentication"
  url: https://api.example.com/profile
  method: GET
  username: myuser
  password: mypassword
  return_content: true

JSON Format:

{
  "type": "uri",
  "description": "Get user profile with authentication",
  "url": "https://api.example.com/profile",
  "method": "GET",
  "username": "myuser",
  "password": "mypassword",
  "return_content": true
}

TOML Format:

[[tasks]]
type = "uri"
description = "Get user profile with authentication"
url = "https://api.example.com/profile"
method = "GET"
username = "myuser"
password = "mypassword"
return_content = true

Register URI response:

YAML Format:

- type: uri
  description: "Get health status"
  url: https://api.example.com/health
  register: health_response
  return_content: true
- type: debug
  msg: "The API status code is: {{ health_response.status }}"

JSON Format:

[
  {
    "type": "uri",
    "description": "Get health status",
    "url": "https://api.example.com/health",
    "register": "health_response",
    "return_content": true
  },
  {
    "type": "debug",
    "msg": "The API status code is: {{ health_response.status }}"
  }
]

TOML Format:

[[tasks]]
type = "uri"
description = "Get health status"
url = "https://api.example.com/health"
register = "health_response"
return_content = true
[[tasks]]
type = "debug"
msg = "The API status code is: {{ health_response.status }}"

Package Management

apt

Description: Debian/Ubuntu package management task

Required Fields:

allow_downgrades (bool): Allow downgrades
allow_unauthenticated (bool): Allow unauthenticated packages
autoclean (bool): Autoclean package cache
autoremove (bool): Autoremove unused packages
cache_valid_time (u32): Cache validity time in seconds
force (bool): Force installation
name (String): Package name
state (PackageState): Package state
update_cache (bool): Update package cache

Optional Fields:

description (Option): Optional description of what this task does

Human-readable description of the task’s purpose. Used for documentation and can be displayed in logs or reports.
when (Option): Optional condition to determine if the task should run

Examples:

Install a package:

YAML Format:

- type: apt
  description: "Install curl package"
  name: curl
  state: present

JSON Format:

{
  "type": "apt",
  "description": "Install curl package",
  "name": "curl",
  "state": "present"
}

TOML Format:

[[tasks]]
type = "apt"
description = "Install curl package"
name = "curl"
state = "present"

Install package with cache update:

YAML Format:

- type: apt
  description: "Install nginx with cache update"
  name: nginx
  state: present
  update_cache: true

JSON Format:

{
  "type": "apt",
  "description": "Install nginx with cache update",
  "name": "nginx",
  "state": "present",
  "update_cache": true
}

TOML Format:

[[tasks]]
type = "apt"
description = "Install nginx with cache update"
name = "nginx"
state = "present"
update_cache = true

Remove a package:

YAML Format:

- type: apt
  description: "Remove apache2 package"
  name: apache2
  state: absent

JSON Format:

{
  "type": "apt",
  "description": "Remove apache2 package",
  "name": "apache2",
  "state": "absent"
}

TOML Format:

[[tasks]]
type = "apt"
description = "Remove apache2 package"
name = "apache2"
state = "absent"

Update package to latest version:

YAML Format:

- type: apt
  description: "Update vim to latest version"
  name: vim
  state: latest
  update_cache: true

JSON Format:

{
  "type": "apt",
  "description": "Update vim to latest version",
  "name": "vim",
  "state": "latest",
  "update_cache": true
}

TOML Format:

[[tasks]]
type = "apt"
description = "Update vim to latest version"
name = "vim"
state = "latest"
update_cache = true

gem

Description: Ruby gem management task

Required Fields:

executable (String): Ruby executable path
extra_args (Vec): Extra arguments
force (bool): Force installation
gem_executable (String): Gem executable path
install_doc (bool): Install documentation
name (String): Gem name
state (PackageState): Gem state
user_install (bool): User installation

Optional Fields:

description (Option): Optional description of what this task does

Human-readable description of the task’s purpose. Used for documentation and can be displayed in logs or reports.
version (Option): Version specification
when (Option): Optional condition to determine if the task should run

Examples:

Install a gem:

YAML Format:

- type: gem
  description: "Install bundler gem"
  name: bundler
  state: present

JSON Format:

{
  "type": "gem",
  "description": "Install bundler gem",
  "name": "bundler",
  "state": "present"
}

TOML Format:

[[tasks]]
type = "gem"
description = "Install bundler gem"
name = "bundler"
state = "present"

Install gem with specific version:

YAML Format:

- type: gem
  description: "Install Rails 7.0"
  name: rails
  state: present
  version: "7.0.0"

JSON Format:

{
  "type": "gem",
  "description": "Install Rails 7.0",
  "name": "rails",
  "state": "present",
  "version": "7.0.0"
}

TOML Format:

[[tasks]]
type = "gem"
description = "Install Rails 7.0"
name = "rails"
state = "present"
version = "7.0.0"

Install gem for specific user:

YAML Format:

- type: gem
  description: "Install jekyll for user"
  name: jekyll
  state: present
  user_install: true

JSON Format:

{
  "type": "gem",
  "description": "Install jekyll for user",
  "name": "jekyll",
  "state": "present",
  "user_install": true
}

TOML Format:

[[tasks]]
type = "gem"
description = "Install jekyll for user"
name = "jekyll"
state = "present"
user_install = true

Remove a gem:

YAML Format:

- type: gem
  description: "Remove bundler gem"
  name: bundler
  state: absent

JSON Format:

{
  "type": "gem",
  "description": "Remove bundler gem",
  "name": "bundler",
  "state": "absent"
}

TOML Format:

[[tasks]]
type = "gem"
description = "Remove bundler gem"
name = "bundler"
state = "absent"

npm

Description: Node.js package management task

Required Fields:

executable (String): NPM executable path
extra_args (Vec): Extra arguments
force (bool): Force installation
global (bool): Global installation
name (String): Package name
production (bool): Production only
state (PackageState): Package state

Optional Fields:

description (Option): Optional description of what this task does

Human-readable description of the task’s purpose. Used for documentation and can be displayed in logs or reports.
registry (Option): Registry URL
version (Option): Version specification
when (Option): Optional condition to determine if the task should run

Examples:

Install an npm package:

YAML Format:

- type: npm
  description: "Install express package"
  name: express
  state: present

JSON Format:

{
  "type": "npm",
  "description": "Install express package",
  "name": "express",
  "state": "present"
}

TOML Format:

[[tasks]]
type = "npm"
description = "Install express package"
name = "express"
state = "present"

Install package globally:

YAML Format:

- type: npm
  description: "Install PM2 globally"
  name: pm2
  state: present
  global: true

JSON Format:

{
  "type": "npm",
  "description": "Install PM2 globally",
  "name": "pm2",
  "state": "present",
  "global": true
}

TOML Format:

[[tasks]]
type = "npm"
description = "Install PM2 globally"
name = "pm2"
state = "present"
global = true

Install specific version:

YAML Format:

- type: npm
  description: "Install React 18"
  name: react
  state: present
  version: "18.2.0"

JSON Format:

{
  "type": "npm",
  "description": "Install React 18",
  "name": "react",
  "state": "present",
  "version": "18.2.0"
}

TOML Format:

[[tasks]]
type = "npm"
description = "Install React 18"
name = "react"
state = "present"
version = "18.2.0"

Remove an npm package:

YAML Format:

- type: npm
  description: "Remove express package"
  name: express
  state: absent

JSON Format:

{
  "type": "npm",
  "description": "Remove express package",
  "name": "express",
  "state": "absent"
}

TOML Format:

[[tasks]]
type = "npm"
description = "Remove express package"
name = "express"
state = "absent"

package

Description: Package management task

Required Fields:

name (String): Package name
state (PackageState): Package state

Optional Fields:

description (Option): Optional description of what this task does

Human-readable description of the task’s purpose. Used for documentation and can be displayed in logs or reports.
manager (Option): Package manager to use (auto-detect if not specified)
register (Option): Optional variable name to register the task result in
when (Option): Optional condition to determine if the task should run

Registered Outputs:

changed (bool): Whether any packages were installed or removed
packages (Vec<String>): List of packages affected

Examples:

Install a package:

YAML Format:

- type: package
  description: "Install nginx web server"
  name: nginx
  state: present

JSON Format:

{
  "type": "package",
  "description": "Install nginx web server",
  "name": "nginx",
  "state": "present"
}

TOML Format:

[[tasks]]
type = "package"
description = "Install nginx web server"
name = "nginx"
state = "present"

Install with specific package manager:

YAML Format:

- type: package
  description: "Install curl using apt"
  name: curl
  state: present
  manager: apt

JSON Format:

{
  "type": "package",
  "description": "Install curl using apt",
  "name": "curl",
  "state": "present",
  "manager": "apt"
}

TOML Format:

[[tasks]]
type = "package"
description = "Install curl using apt"
name = "curl"
state = "present"
manager = "apt"

Update a package to latest version:

YAML Format:

- type: package
  description: "Update vim to latest version"
  name: vim
  state: latest

JSON Format:

{
  "type": "package",
  "description": "Update vim to latest version",
  "name": "vim",
  "state": "latest"
}

TOML Format:

[[tasks]]
type = "package"
description = "Update vim to latest version"
name = "vim"
state = "latest"

Remove a package:

YAML Format:

- type: package
  description: "Remove telnet client"
  name: telnet
  state: absent

JSON Format:

{
  "type": "package",
  "description": "Remove telnet client",
  "name": "telnet",
  "state": "absent"
}

TOML Format:

[[tasks]]
type = "package"
description = "Remove telnet client"
name = "telnet"
state = "absent"

Register package installation:

YAML Format:

- type: package
  description: "Install git and check if changed"
  name: git
  state: present
  register: git_install
- type: debug
  msg: "Git was newly installed"
  when: "{{ git_install.changed }}"

JSON Format:

[
  {
    "type": "package",
    "description": "Install git and check if changed",
    "name": "git",
    "state": "present",
    "register": "git_install"
  },
  {
    "type": "debug",
    "msg": "Git was newly installed",
    "when": "{{ git_install.changed }}"
  }
]

TOML Format:

[[tasks]]
type = "package"
description = "Install git and check if changed"
name = "git"
state = "present"
register = "git_install"
[[tasks]]
type = "debug"
msg = "Git was newly installed"
when = "{{ git_install.changed }}"

pacman

Description: Arch Linux package management task

Required Fields:

force (bool): Force installation/removal
name (String): Package name
reinstall (bool): Force reinstallation
remove_config (bool): Remove configuration files
remove_dependencies (bool): Remove dependencies
state (PackageState): Package state
update_cache (bool): Update package database
upgrade (bool): Upgrade system

Optional Fields:

description (Option): Optional description of what this task does

Human-readable description of the task’s purpose. Used for documentation and can be displayed in logs or reports.
when (Option): Optional condition to determine if the task should run

Examples:

Install a package:

YAML Format:

- type: pacman
  description: "Install vim package"
  name: vim
  state: present

JSON Format:

{
  "type": "pacman",
  "description": "Install vim package",
  "name": "vim",
  "state": "present"
}

TOML Format:

[[tasks]]
type = "pacman"
description = "Install vim package"
name = "vim"
state = "present"

Install with cache update:

YAML Format:

- type: pacman
  description: "Install nginx with cache update"
  name: nginx
  state: present
  update_cache: true

JSON Format:

{
  "type": "pacman",
  "description": "Install nginx with cache update",
  "name": "nginx",
  "state": "present",
  "update_cache": true
}

TOML Format:

[[tasks]]
type = "pacman"
description = "Install nginx with cache update"
name = "nginx"
state = "present"
update_cache = true

Remove a package:

YAML Format:

- type: pacman
  description: "Remove vim package"
  name: vim
  state: absent

JSON Format:

{
  "type": "pacman",
  "description": "Remove vim package",
  "name": "vim",
  "state": "absent"
}

TOML Format:

[[tasks]]
type = "pacman"
description = "Remove vim package"
name = "vim"
state = "absent"

Remove package with dependencies:

YAML Format:

- type: pacman
  description: "Remove package with dependencies"
  name: old-package
  state: absent
  remove_dependencies: true

JSON Format:

{
  "type": "pacman",
  "description": "Remove package with dependencies",
  "name": "old-package",
  "state": "absent",
  "remove_dependencies": true
}

TOML Format:

[[tasks]]
type = "pacman"
description = "Remove package with dependencies"
name = "old-package"
state = "absent"
remove_dependencies = true

pip

Description: Python package management task

Required Fields:

executable (String): Python executable path
extra_args (Vec): Extra arguments
force (bool): Force installation
name (String): Package name
state (PackageState): Package state

Optional Fields:

description (Option): Optional description of what this task does

Human-readable description of the task’s purpose. Used for documentation and can be displayed in logs or reports.
requirements (Option): Requirements file
version (Option): Version specification
virtualenv (Option): Virtual environment path
when (Option): Optional condition to determine if the task should run

Examples:

Install a Python package:

YAML Format:

- type: pip
  description: "Install requests package"
  name: requests
  state: present

JSON Format:

{
  "type": "pip",
  "description": "Install requests package",
  "name": "requests",
  "state": "present"
}

TOML Format:

[[tasks]]
type = "pip"
description = "Install requests package"
name = "requests"
state = "present"

Install package in virtual environment:

YAML Format:

- type: pip
  description: "Install Django in virtualenv"
  name: django
  state: present
  virtualenv: /opt/myapp/venv

JSON Format:

{
  "type": "pip",
  "description": "Install Django in virtualenv",
  "name": "django",
  "state": "present",
  "virtualenv": "/opt/myapp/venv"
}

TOML Format:

[[tasks]]
type = "pip"
description = "Install Django in virtualenv"
name = "django"
state = "present"
virtualenv = "/opt/myapp/venv"

Install specific version:

YAML Format:

- type: pip
  description: "Install Flask 2.0"
  name: flask
  state: present
  version: "2.0.0"

JSON Format:

{
  "type": "pip",
  "description": "Install Flask 2.0",
  "name": "flask",
  "state": "present",
  "version": "2.0.0"
}

TOML Format:

[[tasks]]
type = "pip"
description = "Install Flask 2.0"
name = "flask"
state = "present"
version = "2.0.0"

Remove a Python package:

YAML Format:

- type: pip
  description: "Remove requests package"
  name: requests
  state: absent

JSON Format:

{
  "type": "pip",
  "description": "Remove requests package",
  "name": "requests",
  "state": "absent"
}

TOML Format:

[[tasks]]
type = "pip"
description = "Remove requests package"
name = "requests"
state = "absent"

yum

Description: RHEL/CentOS/Fedora package management task

Required Fields:

allow_downgrades (bool): Allow downgrades
disable_excludes (bool): Disable excludes
disable_gpg_check (bool): Disable GPG check
force (bool): Force installation
install_recommended (bool): Install recommended packages
install_suggested (bool): Install suggested packages
name (String): Package name
state (PackageState): Package state
update_cache (bool): Update package cache

Optional Fields:

description (Option): Optional description of what this task does

Human-readable description of the task’s purpose. Used for documentation and can be displayed in logs or reports.
when (Option): Optional condition to determine if the task should run

Examples:

Install a package:

YAML Format:

- type: yum
  description: "Install nginx web server"
  name: nginx
  state: present

JSON Format:

{
  "type": "yum",
  "description": "Install nginx web server",
  "name": "nginx",
  "state": "present"
}

TOML Format:

[[tasks]]
type = "yum"
description = "Install nginx web server"
name = "nginx"
state = "present"

Install with cache update:

YAML Format:

- type: yum
  description: "Install curl with cache update"
  name: curl
  state: present
  update_cache: true

JSON Format:

{
  "type": "yum",
  "description": "Install curl with cache update",
  "name": "curl",
  "state": "present",
  "update_cache": true
}

TOML Format:

[[tasks]]
type = "yum"
description = "Install curl with cache update"
name = "curl"
state = "present"
update_cache = true

Remove a package:

YAML Format:

- type: yum
  description: "Remove telnet package"
  name: telnet
  state: absent

JSON Format:

{
  "type": "yum",
  "description": "Remove telnet package",
  "name": "telnet",
  "state": "absent"
}

TOML Format:

[[tasks]]
type = "yum"
description = "Remove telnet package"
name = "telnet"
state = "absent"

zypper

Description: SUSE package management task

Required Fields:

allow_downgrades (bool): Allow downgrades
allow_vendor_change (bool): Allow vendor changes
disable_gpg_check (bool): Disable GPG check
force (bool): Force installation
name (String): Package name
state (PackageState): Package state
update_cache (bool): Update package cache

Optional Fields:

description (Option): Optional description of what this task does

Human-readable description of the task’s purpose. Used for documentation and can be displayed in logs or reports.
when (Option): Optional condition to determine if the task should run

Examples:

Install a package:

YAML Format:

- type: zypper
  description: "Install apache web server"
  name: apache2
  state: present

JSON Format:

{
  "type": "zypper",
  "description": "Install apache web server",
  "name": "apache2",
  "state": "present"
}

TOML Format:

[[tasks]]
type = "zypper"
description = "Install apache web server"
name = "apache2"
state = "present"

Install with cache update:

YAML Format:

- type: zypper
  description: "Install vim with repository refresh"
  name: vim
  state: present
  update_cache: true

JSON Format:

{
  "type": "zypper",
  "description": "Install vim with repository refresh",
  "name": "vim",
  "state": "present",
  "update_cache": true
}

TOML Format:

[[tasks]]
type = "zypper"
description = "Install vim with repository refresh"
name = "vim"
state = "present"
update_cache = true

Remove a package:

YAML Format:

- type: zypper
  description: "Remove telnet package"
  name: telnet
  state: absent

JSON Format:

{
  "type": "zypper",
  "description": "Remove telnet package",
  "name": "telnet",
  "state": "absent"
}

TOML Format:

[[tasks]]
type = "zypper"
description = "Remove telnet package"
name = "telnet"
state = "absent"

Security & Access

authorizedkey

Description: SSH authorized key management task

Required Fields:

create_ssh_dir (bool): Whether to create .ssh directory if it doesn’t exist
manage_dir (bool): Whether to manage SSH directory permissions
state (AuthorizedKeyState): SSH state (present/absent)
unique (bool): Whether to deduplicate keys
user (String): Target user for SSH key management
validate_key (bool): Whether to validate key format

Optional Fields:

comment (Option): Comment to identify this key
description (Option): Optional description of what this task does
key (Option): SSH public key content (inline)
key_file (Option): Path to SSH public key file
key_options (Option): Key options (comma-separated list)
path (Option): Path to authorized_keys file (defaults to ~/.ssh/authorized_keys)
when (Option): Optional condition to determine if the task should run

Examples:

Add SSH public key:

YAML Format:

- type: authorized_key
  description: "Add SSH key for admin user"
  user: admin
  state: present
  key: "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABgQC7vbqajDhS... user@host"

JSON Format:

{
  "type": "authorized_key",
  "description": "Add SSH key for admin user",
  "user": "admin",
  "state": "present",
  "key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABgQC7vbqajDhS... user@host"
}

TOML Format:

[[tasks]]
type = "authorized_key"
description = "Add SSH key for admin user"
user = "admin"
state = "present"
key = "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABgQC7vbqajDhS... user@host"

Add SSH key from file:

YAML Format:

- type: authorized_key
  description: "Add SSH key from file"
  user: deploy
  state: present
  key_file: /tmp/id_rsa.pub
  comment: "Deployment key"

JSON Format:

{
  "type": "authorized_key",
  "description": "Add SSH key from file",
  "user": "deploy",
  "state": "present",
  "key_file": "/tmp/id_rsa.pub",
  "comment": "Deployment key"
}

TOML Format:

[[tasks]]
type = "authorized_key"
description = "Add SSH key from file"
user = "deploy"
state = "present"
key_file = "/tmp/id_rsa.pub"
comment = "Deployment key"

Add SSH key with restrictions:

YAML Format:

- type: authorized_key
  description: "Add restricted SSH key"
  user: backup
  state: present
  key: "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABgQC7vbqajDhS... backup@host"
  key_options: "command=\"/usr/local/bin/backup.sh\",no-port-forwarding,no-X11-forwarding,no-agent-forwarding"

JSON Format:

{
  "type": "authorized_key",
  "description": "Add restricted SSH key",
  "user": "backup",
  "state": "present",
  "key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABgQC7vbqajDhS... backup@host",
  "key_options": "command=\"/usr/local/bin/backup.sh\",no-port-forwarding,no-X11-forwarding,no-agent-forwarding"
}

TOML Format:

[[tasks]]
type = "authorized_key"
description = "Add restricted SSH key"
user = "backup"
state = "present"
key = "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABgQC7vbqajDhS... backup@host"
key_options = "command=\"/usr/local/bin/backup.sh\",no-port-forwarding,no-X11-forwarding,no-agent-forwarding"

Remove SSH key:

YAML Format:

- type: authorized_key
  description: "Remove SSH key"
  user: olduser
  state: absent
  key: "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABgQC7vbqajDhS... olduser@host"

JSON Format:

{
  "type": "authorized_key",
  "description": "Remove SSH key",
  "user": "olduser",
  "state": "absent",
  "key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABgQC7vbqajDhS... olduser@host"
}

TOML Format:

[[tasks]]
type = "authorized_key"
description = "Remove SSH key"
user = "olduser"
state = "absent"
key = "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABgQC7vbqajDhS... olduser@host"

firewalld

Description: Firewalld firewall management task

Required Fields:

check_running (bool): Whether to check if firewalld is running
permanent (bool): Whether to make changes permanent
reload (bool): Whether to reload firewall after changes
state (FirewalldState): Firewall state (present/absent)
zone (String): Zone to manage (defaults to “public”)

Optional Fields:

description (Option): Optional description of what this task does
port (Option): Port to manage (e.g., “8080/tcp”, “53/udp”)
rich_rule (Option): Rich rule to manage
service (Option): Service to manage (e.g., “http”, “ssh”)
when (Option): Optional condition to determine if the task should run

Examples:

Allow SSH service:

YAML Format:

- type: firewalld
  description: "Allow SSH access"
  state: present
  service: ssh
  zone: public
  permanent: true

JSON Format:

{
  "type": "firewalld",
  "description": "Allow SSH access",
  "state": "present",
  "service": "ssh",
  "zone": "public",
  "permanent": true
}

TOML Format:

[[tasks]]
type = "firewalld"
description = "Allow SSH access"
state = "present"
service = "ssh"
zone = "public"
permanent = true

Allow custom port:

YAML Format:

- type: firewalld
  description: "Allow web traffic on port 8080"
  state: present
  port: "8080/tcp"
  zone: public
  permanent: true

JSON Format:

{
  "type": "firewalld",
  "description": "Allow web traffic on port 8080",
  "state": "present",
  "port": "8080/tcp",
  "zone": "public",
  "permanent": true
}

TOML Format:

[[tasks]]
type = "firewalld"
description = "Allow web traffic on port 8080"
state = "present"
port = "8080/tcp"
zone = "public"
permanent = true

Add rich rule:

YAML Format:

- type: firewalld
  description: "Allow traffic from specific IP"
  state: present
  rich_rule: 'rule family="ipv4" source address="192.168.1.100" accept'
  zone: public
  permanent: true

JSON Format:

{
  "type": "firewalld",
  "description": "Allow traffic from specific IP",
  "state": "present",
  "rich_rule": "rule family=\"ipv4\" source address=\"192.168.1.100\" accept",
  "zone": "public",
  "permanent": true
}

TOML Format:

[[tasks]]
type = "firewalld"
description = "Allow traffic from specific IP"
state = "present"
rich_rule = 'rule family="ipv4" source address="192.168.1.100" accept'
zone = "public"
permanent = true

Remove firewall rule:

YAML Format:

- type: firewalld
  description: "Remove SSH access"
  state: absent
  service: ssh
  zone: public
  permanent: true

JSON Format:

{
  "type": "firewalld",
  "description": "Remove SSH access",
  "state": "absent",
  "service": "ssh",
  "zone": "public",
  "permanent": true
}

TOML Format:

[[tasks]]
type = "firewalld"
description = "Remove SSH access"
state = "absent"
service = "ssh"
zone = "public"
permanent = true

iptables

Description: iptables firewall management task

Required Fields:

chain (String): Chain to manage (INPUT/OUTPUT/FORWARD/PREROUTING/POSTROUTING)
check_available (bool): Whether to check if iptables is available
extra_args (Vec): Additional iptables arguments
ipv6 (bool): IPv6 mode (use ip6tables instead of iptables)
protocol (String): Protocol (tcp/udp/icmp/all)
state (IptablesState): iptables state (present/absent)
table (String): Table to manage (filter/nat/mangle/raw/security)
target (String): Target/jump action (ACCEPT/DROP/REJECT/LOG/MASQUERADE)

Optional Fields:

description (Option): Optional description of what this task does
destination (Option): Destination IP/network (with optional mask)
dport (Option): Destination port (for tcp/udp)
in_interface (Option): Input interface
out_interface (Option): Output interface
source (Option): Source IP/network (with optional mask)
sport (Option): Source port (for tcp/udp)
when (Option): Optional condition to determine if the task should run

Examples:

Allow SSH access:

YAML Format:

- type: iptables
  description: "Allow SSH access"
  state: present
  table: filter
  chain: INPUT
  protocol: tcp
  dport: "22"
  target: ACCEPT

JSON Format:

{
  "type": "iptables",
  "description": "Allow SSH access",
  "state": "present",
  "table": "filter",
  "chain": "INPUT",
  "protocol": "tcp",
  "dport": "22",
  "target": "ACCEPT"
}

TOML Format:

[[tasks]]
type = "iptables"
description = "Allow SSH access"
state = "present"
table = "filter"
chain = "INPUT"
protocol = "tcp"
dport = "22"
target = "ACCEPT"

Block specific IP address:

YAML Format:

- type: iptables
  description: "Block specific IP address"
  state: present
  table: filter
  chain: INPUT
  source: 192.168.1.100
  target: DROP

JSON Format:

{
  "type": "iptables",
  "description": "Block specific IP address",
  "state": "present",
  "table": "filter",
  "chain": "INPUT",
  "source": "192.168.1.100",
  "target": "DROP"
}

TOML Format:

[[tasks]]
type = "iptables"
description = "Block specific IP address"
state = "present"
table = "filter"
chain = "INPUT"
source = "192.168.1.100"
target = "DROP"

Allow HTTP and HTTPS traffic:

YAML Format:

- type: iptables
  description: "Allow web traffic"
  state: present
  table: filter
  chain: INPUT
  protocol: tcp
  dport: "80,443"
  target: ACCEPT

JSON Format:

{
  "type": "iptables",
  "description": "Allow web traffic",
  "state": "present",
  "table": "filter",
  "chain": "INPUT",
  "protocol": "tcp",
  "dport": "80,443",
  "target": "ACCEPT"
}

TOML Format:

[[tasks]]
type = "iptables"
description = "Allow web traffic"
state = "present"
table = "filter"
chain = "INPUT"
protocol = "tcp"
dport = "80,443"
target = "ACCEPT"

Remove iptables rule:

YAML Format:

- type: iptables
  description: "Remove SSH blocking rule"
  state: absent
  table: filter
  chain: INPUT
  protocol: tcp
  dport: "22"
  target: DROP

JSON Format:

{
  "type": "iptables",
  "description": "Remove SSH blocking rule",
  "state": "absent",
  "table": "filter",
  "chain": "INPUT",
  "protocol": "tcp",
  "dport": "22",
  "target": "DROP"
}

TOML Format:

[[tasks]]
type = "iptables"
description = "Remove SSH blocking rule"
state = "absent"
table = "filter"
chain = "INPUT"
protocol = "tcp"
dport = "22"
target = "DROP"

selinux

Description: SELinux policy management task

Required Fields:

follow (bool): Whether to follow symlinks
ignore_missing (bool): Whether to ignore missing files
persistent (bool): Whether to make changes persistent
recurse (bool): Whether to recurse into directories
state (SelinuxState): SELinux state (present/absent/enforcing/permissive/disabled)

Optional Fields:

boolean (Option): SELinux boolean to manage
context (Option): SELinux context to set
description (Option): Optional description of what this task does
policy (Option): Policy type (targeted/mls)
serange (Option): SELinux level/range to set
serole (Option): SELinux role to set
setype (Option): SELinux type to set
seuser (Option): SELinux user to set
target (Option): File/directory to set context on
when (Option): Optional condition to determine if the task should run

Examples:

Enable SELinux boolean:

YAML Format:

- type: selinux
  description: "Enable httpd_can_network_connect"
  state: on
  boolean: httpd_can_network_connect

JSON Format:

{
  "type": "selinux",
  "description": "Enable httpd_can_network_connect",
  "state": "on",
  "boolean": "httpd_can_network_connect"
}

TOML Format:

[[tasks]]
type = "selinux"
description = "Enable httpd_can_network_connect"
state = "on"
boolean = "httpd_can_network_connect"

Set file context:

YAML Format:

- type: selinux
  description: "Set httpd context for web directory"
  state: context
  target: /var/www/html
  setype: httpd_sys_content_t
  recurse: true

JSON Format:

{
  "type": "selinux",
  "description": "Set httpd context for web directory",
  "state": "context",
  "target": "/var/www/html",
  "setype": "httpd_sys_content_t",
  "recurse": true
}

TOML Format:

[[tasks]]
type = "selinux"
description = "Set httpd context for web directory"
state = "context"
target = "/var/www/html"
setype = "httpd_sys_content_t"
recurse = true

Set SELinux to enforcing mode:

YAML Format:

- type: selinux
  description: "Set SELinux to enforcing mode"
  state: enforcing

JSON Format:

{
  "type": "selinux",
  "description": "Set SELinux to enforcing mode",
  "state": "enforcing"
}

TOML Format:

[[tasks]]
type = "selinux"
description = "Set SELinux to enforcing mode"
state = "enforcing"

Restore file contexts:

YAML Format:

- type: selinux
  description: "Restore SELinux contexts"
  state: restorecon
  target: /etc/httpd
  recurse: true

JSON Format:

{
  "type": "selinux",
  "description": "Restore SELinux contexts",
  "state": "restorecon",
  "target": "/etc/httpd",
  "recurse": true
}

TOML Format:

[[tasks]]
type = "selinux"
description = "Restore SELinux contexts"
state = "restorecon"
target = "/etc/httpd"
recurse = true

sudoers

Description: Sudoers configuration management task

Required Fields:

backup (bool): Backup file before modification
commands (Vec): Commands to allow (defaults to ALL)
group (bool): Whether this is a group (prefix with %)
hosts (Vec): Hosts to allow (defaults to ALL)
name (String): User or group to grant sudo privileges
noexec (bool): NOEXEC option (prevent shell escapes)
nopasswd (bool): NOPASSWD option (don’t require password)
setenv (bool): SETENV option (allow environment variable setting)
state (SudoersState): Sudoers state (present/absent)
validate (bool): Whether to validate sudoers syntax after changes

Optional Fields:

description (Option): Optional description of what this task does
path (Option): Path to sudoers file (defaults to /etc/sudoers)
runas (Option): Run as user (defaults to ALL)
when (Option): Optional condition to determine if the task should run

Examples:

Grant sudo access to user:

YAML Format:

- type: sudoers
  description: "Grant sudo access to admin user"
  state: present
  name: admin
  commands: ["ALL"]
  hosts: ["ALL"]

JSON Format:

{
  "type": "sudoers",
  "description": "Grant sudo access to admin user",
  "state": "present",
  "name": "admin",
  "commands": ["ALL"],
  "hosts": ["ALL"]
}

TOML Format:

[[tasks]]
type = "sudoers"
description = "Grant sudo access to admin user"
state = "present"
name = "admin"
commands = ["ALL"]
hosts = ["ALL"]

Grant sudo access to group:

YAML Format:

- type: sudoers
  description: "Grant sudo access to wheel group"
  state: present
  name: wheel
  group: true
  commands: ["ALL"]
  hosts: ["ALL"]

JSON Format:

{
  "type": "sudoers",
  "description": "Grant sudo access to wheel group",
  "state": "present",
  "name": "wheel",
  "group": true,
  "commands": ["ALL"],
  "hosts": ["ALL"]
}

TOML Format:

[[tasks]]
type = "sudoers"
description = "Grant sudo access to wheel group"
state = "present"
name = "wheel"
group = true
commands = ["ALL"]
hosts = ["ALL"]

Grant passwordless sudo for specific commands:

YAML Format:

- type: sudoers
  description: "Grant passwordless sudo for service management"
  state: present
  name: deploy
  commands: ["/usr/bin/systemctl", "/usr/bin/service"]
  hosts: ["ALL"]
  nopasswd: true

JSON Format:

{
  "type": "sudoers",
  "description": "Grant passwordless sudo for service management",
  "state": "present",
  "name": "deploy",
  "commands": ["/usr/bin/systemctl", "/usr/bin/service"],
  "hosts": ["ALL"],
  "nopasswd": true
}

TOML Format:

[[tasks]]
type = "sudoers"
description = "Grant passwordless sudo for service management"
state = "present"
name = "deploy"
commands = ["/usr/bin/systemctl", "/usr/bin/service"]
hosts = ["ALL"]
nopasswd = true

Remove sudo privileges:

YAML Format:

- type: sudoers
  description: "Remove sudo access from user"
  state: absent
  name: olduser

JSON Format:

{
  "type": "sudoers",
  "description": "Remove sudo access from user",
  "state": "absent",
  "name": "olduser"
}

TOML Format:

[[tasks]]
type = "sudoers"
description = "Remove sudo access from user"
state = "absent"
name = "olduser"

ufw

Description: UFW firewall management task

Required Fields:

state (UfwState): UFW state

Optional Fields:

default (Option): Default policy for chains
description (Option): Optional description of what this task does
direction (Option): Direction (in/out)
from (Option): Source IP/network (for from parameter)
interface (Option): Interface to apply rule to
logging (Option): Logging level
port (Option): Port to manage (e.g., “80”, “443/tcp”, “53/udp”)
proto (Option): Protocol (tcp/udp)
rule (Option): Rule to manage
to (Option): Destination IP/network (for to parameter)
when (Option): Optional condition to determine if the task should run

Examples:

Enable UFW firewall:

YAML Format:

- type: ufw
  description: "Enable UFW firewall"
  state: enabled

JSON Format:

{
  "type": "ufw",
  "description": "Enable UFW firewall",
  "state": "enabled"
}

TOML Format:

[[tasks]]
type = "ufw"
description = "Enable UFW firewall"
state = "enabled"

Allow SSH access:

YAML Format:

- type: ufw
  description: "Allow SSH access"
  state: allow
  port: "22"
  proto: tcp

JSON Format:

{
  "type": "ufw",
  "description": "Allow SSH access",
  "state": "allow",
  "port": "22",
  "proto": "tcp"
}

TOML Format:

[[tasks]]
type = "ufw"
description = "Allow SSH access"
state = "allow"
port = "22"
proto = "tcp"

Allow HTTP and HTTPS:

YAML Format:

- type: ufw
  description: "Allow web traffic"
  state: allow
  port: "80,443"
  proto: tcp

JSON Format:

{
  "type": "ufw",
  "description": "Allow web traffic",
  "state": "allow",
  "port": "80,443",
  "proto": "tcp"
}

TOML Format:

[[tasks]]
type = "ufw"
description = "Allow web traffic"
state = "allow"
port = "80,443"
proto = "tcp"

Deny specific IP address:

YAML Format:

- type: ufw
  description: "Block specific IP address"
  state: deny
  from: 192.168.1.100

JSON Format:

{
  "type": "ufw",
  "description": "Block specific IP address",
  "state": "deny",
  "from": "192.168.1.100"
}

TOML Format:

[[tasks]]
type = "ufw"
description = "Block specific IP address"
state = "deny"
from = "192.168.1.100"

Source Control

git

Description: Git repository management task

Required Fields:

accept_hostkey (bool): Accept host key

Will ensure or not that -o StrictHostKeyChecking=no is present as an ssh option.
clone (bool): Whether to clone if repository doesn’t exist

If false, do not clone the repository even if it does not exist locally.
dest (String): Destination directory

The path of where the repository should be checked out.
force (bool): Whether to force checkout

If true, any modified files in the working repository will be discarded.
recursive (bool): Whether to clone recursively (include submodules)

If false, repository will be cloned without the –recursive option.
remote (String): Remote name

Name of the remote.
repo (String): Git repository URL

The git, SSH, or HTTP(S) protocol address of the git repository.
update (bool): Whether to update the repository

If false, do not retrieve new revisions from the origin repository.
version (String): Version to check out

What version of the repository to check out. This can be the literal string HEAD, a branch name, a tag name, or a SHA-1 hash.

Optional Fields:

depth (Option): Depth for shallow clone

Create a shallow clone with a history truncated to the specified number of revisions.
description (Option): Optional description of what this task does

Human-readable description of the task’s purpose. Used for documentation and can be displayed in logs or reports.
key_file (Option): SSH key file

Specify an optional private key file path to use for the checkout.
register (Option): Optional variable name to register the task result in
ssh_opts (Option): SSH options

Options git will pass to ssh when used as protocol.
when (Option): Optional condition to determine if the task should run

Registered Outputs:

after (String): The SHA-1 hash after the task has run
before (String): The SHA-1 hash before the task has run
changed (bool): Whether the repository was updated or cloned

Examples:

Clone a repository:

YAML Format:

- type: git
  description: "Clone application repository"
  repo: https://github.com/user/myapp.git
  dest: /opt/myapp
  version: main

JSON Format:

{
  "type": "git",
  "description": "Clone application repository",
  "repo": "https://github.com/user/myapp.git",
  "dest": "/opt/myapp",
  "version": "main"
}

TOML Format:

[[tasks]]
type = "git"
description = "Clone application repository"
repo = "https://github.com/user/myapp.git"
dest = "/opt/myapp"
version = "main"

Clone specific branch:

YAML Format:

- type: git
  description: "Clone development branch"
  repo: https://github.com/user/myapp.git
  dest: /opt/myapp-dev
  version: develop

JSON Format:

{
  "type": "git",
  "description": "Clone development branch",
  "repo": "https://github.com/user/myapp.git",
  "dest": "/opt/myapp-dev",
  "version": "develop"
}

TOML Format:

[[tasks]]
type = "git"
description = "Clone development branch"
repo = "https://github.com/user/myapp.git"
dest = "/opt/myapp-dev"
version = "develop"

Clone with submodules:

YAML Format:

- type: git
  description: "Clone repository with submodules"
  repo: https://github.com/user/myapp.git
  dest: /opt/myapp
  recursive: true

JSON Format:

{
  "type": "git",
  "description": "Clone repository with submodules",
  "repo": "https://github.com/user/myapp.git",
  "dest": "/opt/myapp",
  "recursive": true
}

TOML Format:

[[tasks]]
type = "git"
description = "Clone repository with submodules"
repo = "https://github.com/user/myapp.git"
dest = "/opt/myapp"
recursive = true

Clone specific commit:

YAML Format:

- type: git
  description: "Clone specific commit"
  repo: https://github.com/user/myapp.git
  dest: /opt/myapp
  version: abc123def456

JSON Format:

{
  "type": "git",
  "description": "Clone specific commit",
  "repo": "https://github.com/user/myapp.git",
  "dest": "/opt/myapp",
  "version": "abc123def456"
}

TOML Format:

[[tasks]]
type = "git"
description = "Clone specific commit"
repo = "https://github.com/user/myapp.git"
dest = "/opt/myapp"
version = "abc123def456"

Register repository state:

YAML Format:

- type: git
  description: "Clone rust source"
  repo: https://github.com/rust-lang/rust.git
  dest: /opt/rust
  register: rust_repo
- type: debug
  msg: "Rust repo is at {{ rust_repo.after }}"

JSON Format:

[
  {
    "type": "git",
    "description": "Clone rust source",
    "repo": "https://github.com/rust-lang/rust.git",
    "dest": "/opt/rust",
    "register": "rust_repo"
  },
  {
    "type": "debug",
    "msg": "Rust repo is at {{ rust_repo.after }}"
  }
]

TOML Format:

[[tasks]]
type = "git"
description = "Clone rust source"
repo = "https://github.com/rust-lang/rust.git"
dest = "/opt/rust"
register = "rust_repo"
[[tasks]]
type = "debug"
msg = "Rust repo is at {{ rust_repo.after }}"

System Administration

cron

Description: Cron job management task

Required Fields:

day (String): Day of month (1-31, or * for any)
hour (String): Hour (0-23, or * for any)
job (String): Command to execute
minute (String): Minute (0-59, or * for any)
month (String): Month (1-12, or * for any)
name (String): Unique name for this cron job
state (CronState): Cron job state
user (String): User to run the job as
weekday (String): Day of week (0-7, or * for any)

Optional Fields:

comment (Option): Optional comment/description
description (Option): Optional description of what this task does

Human-readable description of the task’s purpose. Used for documentation and can be displayed in logs or reports.
when (Option): Optional condition to determine if the task should run

Examples:

Create a cron job:

YAML Format:

- type: cron
  description: "Create daily backup cron job"
  name: daily-backup
  state: present
  user: root
  minute: "0"
  hour: "2"
  day: "*"
  month: "*"
  weekday: "*"
  job: "/usr/local/bin/backup.sh"

JSON Format:

{
  "type": "cron",
  "description": "Create daily backup cron job",
  "name": "daily-backup",
  "state": "present",
  "user": "root",
  "minute": "0",
  "hour": "2",
  "day": "*",
  "month": "*",
  "weekday": "*",
  "job": "/usr/local/bin/backup.sh"
}

TOML Format:

[[tasks]]
type = "cron"
description = "Create daily backup cron job"
name = "daily-backup"
state = "present"
user = "root"
minute = "0"
hour = "2"
day = "*"
month = "*"
weekday = "*"
job = "/usr/local/bin/backup.sh"

Create cron job with specific schedule:

YAML Format:

- type: cron
  description: "Weekly maintenance on Mondays"
  name: weekly-maintenance
  state: present
  user: root
  minute: "0"
  hour: "9"
  day: "*"
  month: "*"
  weekday: "1"
  job: "/usr/local/bin/maintenance.sh"
  comment: "Weekly system maintenance"

JSON Format:

{
  "type": "cron",
  "description": "Weekly maintenance on Mondays",
  "name": "weekly-maintenance",
  "state": "present",
  "user": "root",
  "minute": "0",
  "hour": "9",
  "day": "*",
  "month": "*",
  "weekday": "1",
  "job": "/usr/local/bin/maintenance.sh",
  "comment": "Weekly system maintenance"
}

TOML Format:

[[tasks]]
type = "cron"
description = "Weekly maintenance on Mondays"
name = "weekly-maintenance"
state = "present"
user = "root"
minute = "0"
hour = "9"
day = "*"
month = "*"
weekday = "1"
job = "/usr/local/bin/maintenance.sh"
comment = "Weekly system maintenance"

Remove a cron job:

YAML Format:

- type: cron
  description: "Remove daily backup cron job"
  name: daily-backup
  state: absent

JSON Format:

{
  "type": "cron",
  "description": "Remove daily backup cron job",
  "name": "daily-backup",
  "state": "absent"
}

TOML Format:

[[tasks]]
type = "cron"
description = "Remove daily backup cron job"
name = "daily-backup"
state = "absent"

Cron job with complex schedule:

YAML Format:

- type: cron
  description: "Monitor service every 15 minutes during business hours"
  name: service-monitor
  state: present
  user: monitor
  minute: "*/15"
  hour: "9-17"
  day: "1-5"
  month: "*"
  weekday: "*"
  job: "/usr/local/bin/check-service.sh"
  comment: "Business hours service monitoring"

JSON Format:

{
  "type": "cron",
  "description": "Monitor service every 15 minutes during business hours",
  "name": "service-monitor",
  "state": "present",
  "user": "monitor",
  "minute": "*/15",
  "hour": "9-17",
  "day": "1-5",
  "month": "*",
  "weekday": "*",
  "job": "/usr/local/bin/check-service.sh",
  "comment": "Business hours service monitoring"
}

TOML Format:

[[tasks]]
type = "cron"
description = "Monitor service every 15 minutes during business hours"
name = "service-monitor"
state = "present"
user = "monitor"
minute = "*/15"
hour = "9-17"
day = "1-5"
month = "*"
weekday = "*"
job = "/usr/local/bin/check-service.sh"
comment = "Business hours service monitoring"

filesystem

Description: Filesystem creation/deletion task

Required Fields:

dev (String): Device path
force (bool): Force filesystem creation (dangerous!)
opts (Vec): Additional mkfs options
state (FilesystemState): Filesystem state

Optional Fields:

description (Option): Optional description of what this task does

Human-readable description of the task’s purpose. Used for documentation and can be displayed in logs or reports.
fstype (Option): Filesystem type (ext4, xfs, btrfs, etc.)
when (Option): Optional condition to determine if the task should run

Examples:

Create an ext4 filesystem:

YAML Format:

- type: filesystem
  description: "Create ext4 filesystem"
  dev: /dev/sdb1
  state: present
  fstype: ext4

JSON Format:

{
  "type": "filesystem",
  "description": "Create ext4 filesystem",
  "dev": "/dev/sdb1",
  "state": "present",
  "fstype": "ext4"
}

TOML Format:

[[tasks]]
type = "filesystem"
description = "Create ext4 filesystem"
dev = "/dev/sdb1"
state = "present"
fstype = "ext4"

Create an XFS filesystem:

YAML Format:

- type: filesystem
  description: "Create XFS filesystem"
  dev: /dev/sdc1
  state: present
  fstype: xfs
  opts: ["-f", "-i", "size=512"]

JSON Format:

{
  "type": "filesystem",
  "description": "Create XFS filesystem",
  "dev": "/dev/sdc1",
  "state": "present",
  "fstype": "xfs",
  "opts": ["-f", "-i", "size=512"]
}

TOML Format:

[[tasks]]
type = "filesystem"
description = "Create XFS filesystem"
dev = "/dev/sdc1"
state = "present"
fstype = "xfs"
opts = ["-f", "-i", "size=512"]

Create a Btrfs filesystem:

YAML Format:

- type: filesystem
  description: "Create Btrfs filesystem"
  dev: /dev/sdd1
  state: present
  fstype: btrfs

JSON Format:

{
  "type": "filesystem",
  "description": "Create Btrfs filesystem",
  "dev": "/dev/sdd1",
  "state": "present",
  "fstype": "btrfs"
}

TOML Format:

[[tasks]]
type = "filesystem"
description = "Create Btrfs filesystem"
dev = "/dev/sdd1"
state = "present"
fstype = "btrfs"

Force create filesystem:

YAML Format:

- type: filesystem
  description: "Force create ext4 filesystem"
  dev: /dev/sde1
  state: present
  fstype: ext4
  force: true

JSON Format:

{
  "type": "filesystem",
  "description": "Force create ext4 filesystem",
  "dev": "/dev/sde1",
  "state": "present",
  "fstype": "ext4",
  "force": true
}

TOML Format:

[[tasks]]
type = "filesystem"
description = "Force create ext4 filesystem"
dev = "/dev/sde1"
state = "present"
fstype = "ext4"
force = true

group

Description: Group management task

Required Fields:

name (String): Group name
state (GroupState): Group state
system (bool): Whether group is a system group

Optional Fields:

description (Option): Optional description of what this task does

Human-readable description of the task’s purpose. Used for documentation and can be displayed in logs or reports.
gid (Option): Group ID
when (Option): Optional condition to determine if the task should run

Examples:

Create a group:

YAML Format:

- type: group
  description: "Create a web application group"
  name: webapp
  state: present
  gid: 1001

JSON Format:

{
  "type": "group",
  "description": "Create a web application group",
  "name": "webapp",
  "state": "present",
  "gid": 1001
}

TOML Format:

[[tasks]]
type = "group"
description = "Create a web application group"
name = "webapp"
state = "present"
gid = 1001

Create a system group:

YAML Format:

- type: group
  description: "Create a system group for nginx"
  name: nginx
  state: present
  system: true

JSON Format:

{
  "type": "group",
  "description": "Create a system group for nginx",
  "name": "nginx",
  "state": "present",
  "system": true
}

TOML Format:

[[tasks]]
type = "group"
description = "Create a system group for nginx"
name = "nginx"
state = "present"
system = true

Remove a group:

YAML Format:

- type: group
  description: "Remove the old group"
  name: oldgroup
  state: absent

JSON Format:

{
  "type": "group",
  "description": "Remove the old group",
  "name": "oldgroup",
  "state": "absent"
}

TOML Format:

[[tasks]]
type = "group"
description = "Remove the old group"
name = "oldgroup"
state = "absent"

hostname

Description: System hostname management task

Required Fields:

name (String): Desired hostname
persist (bool): Whether to persist hostname to /etc/hostname

Optional Fields:

description (Option): Optional description of what this task does

Human-readable description of the task’s purpose. Used for documentation and can be displayed in logs or reports.
when (Option): Optional condition to determine if the task should run

Examples:

Set system hostname:

YAML Format:

- type: hostname
  description: "Set system hostname"
  name: web-server-01
  persist: true

JSON Format:

{
  "type": "hostname",
  "description": "Set system hostname",
  "name": "web-server-01",
  "persist": true
}

TOML Format:

[[tasks]]
type = "hostname"
description = "Set system hostname"
name = "web-server-01"
persist = true

Set hostname temporarily:

YAML Format:

- type: hostname
  description: "Set temporary hostname"
  name: temp-server
  persist: false

JSON Format:

{
  "type": "hostname",
  "description": "Set temporary hostname",
  "name": "temp-server",
  "persist": false
}

TOML Format:

[[tasks]]
type = "hostname"
description = "Set temporary hostname"
name = "temp-server"
persist = false

Set hostname with domain:

YAML Format:

- type: hostname
  description: "Set fully qualified hostname"
  name: app.example.com
  persist: true

JSON Format:

{
  "type": "hostname",
  "description": "Set fully qualified hostname",
  "name": "app.example.com",
  "persist": true
}

TOML Format:

[[tasks]]
type = "hostname"
description = "Set fully qualified hostname"
name = "app.example.com"
persist = true

mount

Description: Filesystem mounting task

Required Fields:

fstab (bool): Whether to update /etc/fstab
opts (Vec): Mount options
path (String): Mount point path
recursive (bool): Whether to mount recursively
src (String): Device to mount (device path, UUID, LABEL, etc.)
state (MountState): Mount state

Optional Fields:

description (Option): Optional description of what this task does

Human-readable description of the task’s purpose. Used for documentation and can be displayed in logs or reports.
fstype (Option): Filesystem type
when (Option): Optional condition to determine if the task should run

Examples:

Mount a filesystem:

YAML Format:

- type: mount
  description: "Mount data partition"
  path: /mnt/data
  state: mounted
  src: /dev/sdb1
  fstype: ext4
  opts: ["defaults"]

JSON Format:

{
  "type": "mount",
  "description": "Mount data partition",
  "path": "/mnt/data",
  "state": "mounted",
  "src": "/dev/sdb1",
  "fstype": "ext4",
  "opts": ["defaults"]
}

TOML Format:

[[tasks]]
type = "mount"
description = "Mount data partition"
path = "/mnt/data"
state = "mounted"
src = "/dev/sdb1"
fstype = "ext4"
opts = ["defaults"]

Mount with fstab entry:

YAML Format:

- type: mount
  description: "Mount NFS share with fstab entry"
  path: /mnt/nfs
  state: present
  src: 192.168.1.100:/export/data
  fstype: nfs
  opts: ["defaults", "vers=4"]
  fstab: true

JSON Format:

{
  "type": "mount",
  "description": "Mount NFS share with fstab entry",
  "path": "/mnt/nfs",
  "state": "present",
  "src": "192.168.1.100:/export/data",
  "fstype": "nfs",
  "opts": ["defaults", "vers=4"],
  "fstab": true
}

TOML Format:

[[tasks]]
type = "mount"
description = "Mount NFS share with fstab entry"
path = "/mnt/nfs"
state = "present"
src = "192.168.1.100:/export/data"
fstype = "nfs"
opts = ["defaults", "vers=4"]
fstab = true

Unmount a filesystem:

YAML Format:

- type: mount
  description: "Unmount temporary mount"
  path: /mnt/temp
  state: unmounted

JSON Format:

{
  "type": "mount",
  "description": "Unmount temporary mount",
  "path": "/mnt/temp",
  "state": "unmounted"
}

TOML Format:

[[tasks]]
type = "mount"
description = "Unmount temporary mount"
path = "/mnt/temp"
state = "unmounted"

Remove fstab entry:

YAML Format:

- type: mount
  description: "Remove fstab entry"
  path: /mnt/old
  state: absent
  fstab: true

JSON Format:

{
  "type": "mount",
  "description": "Remove fstab entry",
  "path": "/mnt/old",
  "state": "absent",
  "fstab": true
}

TOML Format:

[[tasks]]
type = "mount"
description = "Remove fstab entry"
path = "/mnt/old"
state = "absent"
fstab = true

reboot

Description: System reboot task

Required Fields:

delay (u32): Delay before reboot (seconds)
force (bool): Whether to force reboot (don’t wait for clean shutdown)
test (bool): Test mode (don’t actually reboot)

Optional Fields:

description (Option): Optional description of what this task does

Human-readable description of the task’s purpose. Used for documentation and can be displayed in logs or reports.
msg (Option): Message to display before reboot
when (Option): Optional condition to determine if the task should run

Examples:

Reboot system with delay:

YAML Format:

- type: reboot
  description: "Reboot system after kernel update"
  delay: 60
  msg: "System will reboot in 60 seconds for kernel update"
  force: false

JSON Format:

{
  "type": "reboot",
  "description": "Reboot system after kernel update",
  "delay": 60,
  "msg": "System will reboot in 60 seconds for kernel update",
  "force": false
}

TOML Format:

[[tasks]]
type = "reboot"
description = "Reboot system after kernel update"
delay = 60
msg = "System will reboot in 60 seconds for kernel update"
force = false

Immediate reboot:

YAML Format:

- type: reboot
  description: "Immediate system reboot"
  delay: 0
  force: true

JSON Format:

{
  "type": "reboot",
  "description": "Immediate system reboot",
  "delay": 0,
  "force": true
}

TOML Format:

[[tasks]]
type = "reboot"
description = "Immediate system reboot"
delay = 0
force = true

Test reboot (dry run):

YAML Format:

- type: reboot
  description: "Test reboot configuration"
  delay: 30
  msg: "This is a test reboot - system will not actually reboot"
  force: false
  test: true

JSON Format:

{
  "type": "reboot",
  "description": "Test reboot configuration",
  "delay": 30,
  "msg": "This is a test reboot - system will not actually reboot",
  "force": false,
  "test": true
}

TOML Format:

[[tasks]]
type = "reboot"
description = "Test reboot configuration"
delay = 30
msg = "This is a test reboot - system will not actually reboot"
force = false
test = true

service

Description: Service management task

Required Fields:

name (String): Service name
state (ServiceState): Service state

Optional Fields:

description (Option): Optional description of what this task does

Human-readable description of the task’s purpose. Used for documentation and can be displayed in logs or reports.
enabled (Option): Whether to enable service at boot
manager (Option): Service manager to use (auto-detect if not specified)
when (Option): Optional condition to determine if the task should run

Examples:

Start and enable a service:

YAML Format:

- type: service
  description: "Start and enable nginx service"
  name: nginx
  state: started
  enabled: true

JSON Format:

{
  "type": "service",
  "description": "Start and enable nginx service",
  "name": "nginx",
  "state": "started",
  "enabled": true
}

TOML Format:

[[tasks]]
type = "service"
description = "Start and enable nginx service"
name = "nginx"
state = "started"
enabled = true

shutdown

Description: System shutdown task

Required Fields:

delay (u32): Delay before shutdown (seconds)
force (bool): Whether to force shutdown (don’t wait for clean shutdown)
test (bool): Test mode (don’t actually shutdown)

Optional Fields:

description (Option): Optional description of what this task does

Human-readable description of the task’s purpose. Used for documentation and can be displayed in logs or reports.
msg (Option): Message to display before shutdown
when (Option): Optional condition to determine if the task should run

Examples:

Shutdown system with delay:

YAML Format:

- type: shutdown
  description: "Shutdown system for maintenance"
  delay: 30
  msg: "System will shutdown in 30 seconds for maintenance"
  force: false

JSON Format:

{
  "type": "shutdown",
  "description": "Shutdown system for maintenance",
  "delay": 30,
  "msg": "System will shutdown in 30 seconds for maintenance",
  "force": false
}

TOML Format:

[[tasks]]
type = "shutdown"
description = "Shutdown system for maintenance"
delay = 30
msg = "System will shutdown in 30 seconds for maintenance"
force = false

Immediate shutdown:

YAML Format:

- type: shutdown
  description: "Immediate system shutdown"
  delay: 0
  force: true

JSON Format:

{
  "type": "shutdown",
  "description": "Immediate system shutdown",
  "delay": 0,
  "force": true
}

TOML Format:

[[tasks]]
type = "shutdown"
description = "Immediate system shutdown"
delay = 0
force = true

Test shutdown (dry run):

YAML Format:

- type: shutdown
  description: "Test shutdown configuration"
  delay: 60
  msg: "This is a test shutdown - system will not actually shutdown"
  force: false
  test: true

JSON Format:

{
  "type": "shutdown",
  "description": "Test shutdown configuration",
  "delay": 60,
  "msg": "This is a test shutdown - system will not actually shutdown",
  "force": false,
  "test": true
}

TOML Format:

[[tasks]]
type = "shutdown"
description = "Test shutdown configuration"
delay = 60
msg = "This is a test shutdown - system will not actually shutdown"
force = false
test = true

sysctl

Description: Kernel parameter management task

Required Fields:

name (String): Parameter name (e.g., “net.ipv4.ip_forward”)
persist (bool): Whether to persist changes to /etc/sysctl.conf
reload (bool): Whether to reload immediately
state (SysctlState): Parameter state
value (String): Parameter value

Optional Fields:

description (Option): Optional description of what this task does

Human-readable description of the task’s purpose. Used for documentation and can be displayed in logs or reports.
when (Option): Optional condition to determine if the task should run

Examples:

Set kernel parameter:

YAML Format:

- type: sysctl
  description: "Enable IP forwarding"
  name: net.ipv4.ip_forward
  state: present
  value: "1"
  persist: true

JSON Format:

{
  "type": "sysctl",
  "description": "Enable IP forwarding",
  "name": "net.ipv4.ip_forward",
  "state": "present",
  "value": "1",
  "persist": true
}

TOML Format:

[[tasks]]
type = "sysctl"
description = "Enable IP forwarding"
name = "net.ipv4.ip_forward"
state = "present"
value = "1"
persist = true

Configure network buffer sizes:

YAML Format:

- type: sysctl
  description: "Increase network buffer sizes"
  name: net.core.rmem_max
  state: present
  value: "16777216"
  persist: true

JSON Format:

{
  "type": "sysctl",
  "description": "Increase network buffer sizes",
  "name": "net.core.rmem_max",
  "state": "present",
  "value": "16777216",
  "persist": true
}

TOML Format:

[[tasks]]
type = "sysctl"
description = "Increase network buffer sizes"
name = "net.core.rmem_max"
state = "present"
value = "16777216"
persist = true

Disable IPv6:

YAML Format:

- type: sysctl
  description: "Disable IPv6"
  name: net.ipv6.conf.all.disable_ipv6
  state: present
  value: "1"
  persist: true

JSON Format:

{
  "type": "sysctl",
  "description": "Disable IPv6",
  "name": "net.ipv6.conf.all.disable_ipv6",
  "state": "present",
  "value": "1",
  "persist": true
}

TOML Format:

[[tasks]]
type = "sysctl"
description = "Disable IPv6"
name = "net.ipv6.conf.all.disable_ipv6"
state = "present"
value = "1"
persist = true

Remove sysctl parameter:

YAML Format:

- type: sysctl
  description: "Remove custom sysctl parameter"
  name: net.ipv4.tcp_tw_reuse
  state: absent

JSON Format:

{
  "type": "sysctl",
  "description": "Remove custom sysctl parameter",
  "name": "net.ipv4.tcp_tw_reuse",
  "state": "absent"
}

TOML Format:

[[tasks]]
type = "sysctl"
description = "Remove custom sysctl parameter"
name = "net.ipv4.tcp_tw_reuse"
state = "absent"

timezone

Description: System timezone management task

Required Fields:

name (String): Timezone name (e.g., “America/New_York”, “UTC”)

Optional Fields:

description (Option): Optional description of what this task does

Human-readable description of the task’s purpose. Used for documentation and can be displayed in logs or reports.
when (Option): Optional condition to determine if the task should run

Examples:

Set system timezone to UTC:

YAML Format:

- type: timezone
  description: "Set system timezone to UTC"
  name: UTC

JSON Format:

{
  "type": "timezone",
  "description": "Set system timezone to UTC",
  "name": "UTC"
}

TOML Format:

[[tasks]]
type = "timezone"
description = "Set system timezone to UTC"
name = "UTC"

Set timezone to Eastern Time:

YAML Format:

- type: timezone
  description: "Set timezone to Eastern Time"
  name: America/New_York

JSON Format:

{
  "type": "timezone",
  "description": "Set timezone to Eastern Time",
  "name": "America/New_York"
}

TOML Format:

[[tasks]]
type = "timezone"
description = "Set timezone to Eastern Time"
name = "America/New_York"

Set timezone to Pacific Time:

YAML Format:

- type: timezone
  description: "Set timezone to Pacific Time"
  name: America/Los_Angeles

JSON Format:

{
  "type": "timezone",
  "description": "Set timezone to Pacific Time",
  "name": "America/Los_Angeles"
}

TOML Format:

[[tasks]]
type = "timezone"
description = "Set timezone to Pacific Time"
name = "America/Los_Angeles"

user

Description: User and group management task

Required Fields:

groups (Vec): Additional groups
name (String): Username
state (UserState): User state

Optional Fields:

create_home (Option): Whether to create home directory
description (Option): Optional description of what this task does

Human-readable description of the task’s purpose. Used for documentation and can be displayed in logs or reports.
gid (Option): Group ID
home (Option): Home directory
password (Option): Password (hashed)
shell (Option): Shell
uid (Option): User ID
when (Option): Optional condition to determine if the task should run

Examples:

Create a user with basic settings:

YAML Format:

- type: user
  description: "Create a web application user"
  name: webapp
  state: present
  uid: 1001
  gid: 1001
  home: /home/webapp
  shell: /bin/bash
  create_home: true

JSON Format:

{
  "type": "user",
  "description": "Create a web application user",
  "name": "webapp",
  "state": "present",
  "uid": 1001,
  "gid": 1001,
  "home": "/home/webapp",
  "shell": "/bin/bash",
  "create_home": true
}

TOML Format:

[[tasks]]
type = "user"
description = "Create a web application user"
name = "webapp"
state = "present"
uid = 1001
gid = 1001
home = "/home/webapp"
shell = "/bin/bash"
create_home = true

Create a system user:

YAML Format:

- type: user
  description: "Create a system user for nginx"
  name: nginx
  state: present
  uid: 33
  gid: 33
  home: /var/lib/nginx
  shell: /usr/sbin/nologin
  create_home: false

JSON Format:

{
  "type": "user",
  "description": "Create a system user for nginx",
  "name": "nginx",
  "state": "present",
  "uid": 33,
  "gid": 33,
  "home": "/var/lib/nginx",
  "shell": "/usr/sbin/nologin",
  "create_home": false
}

TOML Format:

[[tasks]]
type = "user"
description = "Create a system user for nginx"
name = "nginx"
state = "present"
uid = 33
gid = 33
home = "/var/lib/nginx"
shell = "/usr/sbin/nologin"
create_home = false

Remove a user:

YAML Format:

- type: user
  description: "Remove the old user account"
  name: olduser
  state: absent

JSON Format:

{
  "type": "user",
  "description": "Remove the old user account",
  "name": "olduser",
  "state": "absent"
}

TOML Format:

[[tasks]]
type = "user"
description = "Remove the old user account"
name = "olduser"
state = "absent"

Utility/Control

assert

Description: Assert task for validating conditions

Required Fields:

quiet (bool): Quiet mode

Don’t show success messages.
that (String): Condition to assert

Boolean expression that must evaluate to true.

Optional Fields:

description (Option): Optional description of what this task does

Human-readable description of the task’s purpose. Used for documentation and can be displayed in logs or reports.
fail_msg (Option): Failure message

Message to display when assertion fails.
success_msg (Option): Success message

Message to display when assertion passes.
when (Option): Optional condition to determine if the task should run

Examples:

Assert a condition:

YAML Format:

- type: assert
  description: "Verify nginx is installed"
  that: "'nginx' in installed_packages"
  success_msg: "Nginx is properly installed"
  fail_msg: "Nginx installation failed"

JSON Format:

[
  {
    "type": "assert",
    "description": "Verify nginx is installed",
    "that": "'nginx' in installed_packages",
    "success_msg": "Nginx is properly installed",
    "fail_msg": "Nginx installation failed"
  }
]

TOML Format:

[[tasks]]
type = "assert"
description = "Verify nginx is installed"
that = "'nginx' in installed_packages"
success_msg = "Nginx is properly installed"
fail_msg = "Nginx installation failed"

debug

Description: Debug task for displaying information

Required Fields:

msg (String): Message to display

The message to print. Can be a string or variable reference.
verbosity (DebugVerbosity): Verbosity level

Control when this debug message is shown (normal/verbose).

Optional Fields:

description (Option): Optional description of what this task does

Human-readable description of the task’s purpose. Used for documentation and can be displayed in logs or reports.
var (Option): Variable to debug

Variable name to display value of. Alternative to msg.
when (Option): Optional condition to determine if the task should run

Examples:

Display a debug message:

YAML Format:

- type: debug
  description: "Show current configuration"
  msg: "Current web_root: {{ web_root }}"
  verbosity: normal

JSON Format:

[
  {
    "type": "debug",
    "description": "Show current configuration",
    "msg": "Current web_root: {{ web_root }}",
    "verbosity": "normal"
  }
]

TOML Format:

[[tasks]]
type = "debug"
description = "Show current configuration"
msg = "Current web_root: {{ web_root }}"
verbosity = "normal"

fail

Description: Fail task for forcing execution failure

Required Fields:

msg (String): Failure message

Message to display when failing.

Optional Fields:

description (Option): Optional description of what this task does

Human-readable description of the task’s purpose. Used for documentation and can be displayed in logs or reports.
when (Option): Optional condition to determine if the task should run

Examples:

Fail with a message:

YAML Format:

- type: fail
  description: "Stop execution if requirements not met"
  msg: "System requirements not satisfied"
  when: "not requirements_met"

JSON Format:

[
  {
    "type": "fail",
    "description": "Stop execution if requirements not met",
    "msg": "System requirements not satisfied",
    "when": "not requirements_met"
  }
]

TOML Format:

[[tasks]]
type = "fail"
description = "Stop execution if requirements not met"
msg = "System requirements not satisfied"
when = "not requirements_met"

includerole

Description: Include role task for reusable configurations

Required Fields:

defaults (HashMap<String, Value>): Default variables

Default variables for the role.
name (String): Role name

Name of the role to include.
vars (HashMap<String, Value>): Variable overrides

Variables to pass to the role.

Optional Fields:

description (Option): Optional description of what this task does

Human-readable description of the task’s purpose. Used for documentation and can be displayed in logs or reports.
when (Option): Optional condition to determine if the task should run

Examples:

Include a role:

YAML Format:

- type: include_role
  description: "Setup web server"
  name: webserver
  when: "webserver_required"
  vars:
    port: 8080
  defaults:
    document_root: /var/www/html

JSON Format:

[
  {
    "type": "include_role",
    "description": "Setup web server",
    "name": "webserver",
    "when": "webserver_required",
    "vars": {
      "port": 8080
    },
    "defaults": {
      "document_root": "/var/www/html"
    }
  }
]

TOML Format:

[[tasks]]
type = "include_role"
description = "Setup web server"
name = "webserver"
when = "webserver_required"
[tasks.vars]
port = 8080
[tasks.defaults]
document_root = "/var/www/html"

includetasks

Description: Include tasks task for modular configurations

Required Fields:

file (String): File to include

Path to the task file to include.
vars (HashMap<String, Value>): Variable overrides

Variables to pass to the included tasks.

Optional Fields:

description (Option): Optional description of what this task does

Human-readable description of the task’s purpose. Used for documentation and can be displayed in logs or reports.
when (Option): Optional condition to determine if the task should run

Examples:

Include a task file:

YAML Format:

- type: include_tasks
  description: "Include common setup tasks"
  file: common/setup.yml
  when: "setup_required"
  vars:
    app_name: myapp

JSON Format:

[
  {
    "type": "include_tasks",
    "description": "Include common setup tasks",
    "file": "common/setup.yml",
    "when": "setup_required",
    "vars": {
      "app_name": "myapp"
    }
  }
]

TOML Format:

[[tasks]]
type = "include_tasks"
description = "Include common setup tasks"
file = "common/setup.yml"
when = "setup_required"
[tasks.vars]
app_name = "myapp"

pause

Description: Pause task to halt execution

Required Fields:

minutes (u64): Minutes to pause

Duration to pause execution in minutes.
prompt (String): Message to display during pause

Message shown to user during pause.
seconds (u64): Seconds to pause

Duration to pause execution in seconds.

Optional Fields:

description (Option): Optional description of what this task does

Human-readable description of the task’s purpose. Used for documentation and can be displayed in logs or reports.
when (Option): Optional condition to determine if the task should run

Examples:

Pause execution:

YAML Format:

- type: pause
  description: "Wait for services to start"
  prompt: "Waiting for services to initialize..."
  seconds: 30

JSON Format:

[
  {
    "type": "pause",
    "description": "Wait for services to start",
    "prompt": "Waiting for services to initialize...",
    "seconds": 30
  }
]

TOML Format:

[[tasks]]
type = "pause"
description = "Wait for services to start"
prompt = "Waiting for services to initialize..."
seconds = 30

setfact

Description: Set fact task for variable management

Required Fields:

cacheable (bool): Cacheable flag

Whether this fact can be cached between runs.
key (String): Variable name

Name of the fact/variable to set.
value (Value): Variable value

Value to assign to the variable.

Optional Fields:

description (Option): Optional description of what this task does

Human-readable description of the task’s purpose. Used for documentation and can be displayed in logs or reports.
when (Option): Optional condition to determine if the task should run

Examples:

Set a fact:

YAML Format:

- type: set_fact
  description: "Set application version"
  key: app_version
  value: "1.2.3"
  cacheable: true

JSON Format:

[
  {
    "type": "set_fact",
    "description": "Set application version",
    "key": "app_version",
    "value": "1.2.3",
    "cacheable": true
  }
]

TOML Format:

[[tasks]]
type = "set_fact"
description = "Set application version"
key = "app_version"
value = "1.2.3"
cacheable = true

waitfor

Description: Wait for task for synchronization

Required Fields:

active_connection (bool): Active connection check

Perform active connection attempt instead of just port scan.
delay (u64): Delay between checks

Time to wait between connectivity checks.
state (ConnectionState): Connection state to wait for

Whether to wait for connection to be started or stopped.
timeout (u64): Timeout in seconds

Maximum time to wait for condition.

Optional Fields:

description (Option): Optional description of what this task does

Human-readable description of the task’s purpose. Used for documentation and can be displayed in logs or reports.
host (Option): Host to wait for connectivity

Hostname or IP address to check connectivity.
path (Option): Path to file to wait for

File path to wait for existence or non-existence.
port (Option): Port to check

Port number to check for connectivity.
when (Option): Optional condition to determine if the task should run

Examples:

Wait for port connectivity:

YAML Format:

- type: wait_for
  description: "Wait for web server to start"
  host: localhost
  port: 80
  timeout: 60
  delay: 5

JSON Format:

[
  {
    "type": "wait_for",
    "description": "Wait for web server to start",
    "host": "localhost",
    "port": 80,
    "timeout": 60,
    "delay": 5
  }
]

TOML Format:

[[tasks]]
type = "wait_for"
description = "Wait for web server to start"
host = "localhost"
port = 80
timeout = 60
delay = 5

Facts Collectors (`facts`)

Facts collectors gather system metrics and inventory information. Each collector corresponds to a specific type of system information or metric.

Collector Configuration

All facts collectors support common configuration fields for controlling collection behavior:

name: Collector name (used for metric names)
enabled: Whether this collector is enabled (default: true)
poll_interval: Poll interval in seconds (how often to collect this metric)
labels: Additional labels for this collector

CPU Metrics

cpu

Description: Collect CPU usage, frequency, temperature, and load average metrics

Required Fields:

base (BaseCollector): No description available
collect (CpuCollectOptions): CPU metrics to collect
name (String): Collector name (used for metric names)
poll_interval (u64): Poll interval in seconds (how often to collect this metric)
thresholds (CpuThresholds): Thresholds for alerts

Optional Fields:

enabled (bool): Whether this collector is enabled (default: true)
labels (HashMap<String, String>): Additional labels for this collector

Examples:

Basic CPU metrics collection:

YAML Format:

type: cpu
name: cpu
poll_interval: 30
collect:
  usage: true
  per_core: true
  frequency: true
  temperature: true
  load_average: true
thresholds:
  usage_warning: 80.0
  usage_critical: 95.0
  temp_warning: 70.0
  temp_critical: 85.0

JSON Format:

{
  "type": "cpu",
  "name": "cpu",
  "poll_interval": 30,
  "collect": {
    "usage": true,
    "per_core": true,
    "frequency": true,
    "temperature": true,
    "load_average": true
  },
  "thresholds": {
    "usage_warning": 80.0,
    "usage_critical": 95.0,
    "temp_warning": 70.0,
    "temp_critical": 85.0
  }
}

TOML Format:

[[collectors]]
type = "cpu"
name = "cpu"
poll_interval = 30
[collectors.collect]
usage = true
per_core = true
frequency = true
temperature = true
load_average = true
[collectors.thresholds]
usage_warning = 80.0
usage_critical = 95.0
temp_warning = 70.0
temp_critical = 85.0

Output:

 cpu_count: 4
 usage_percent: 45.2
 usage_warning: false
 usage_critical: false
 cores:
   - core_id: 0
     usage_percent: 42.1
     frequency_mhz: 2400
   - core_id: 1
     usage_percent: 48.3
     frequency_mhz: 2400
 frequency_mhz: 2400.0
 temperature_celsius: null
 temperature_available: false
 temp_warning: false
 temp_critical: false
 load_average:
   "1m": 1.25
   "5m": 1.15
   "15m": 1.08

Command Output

command

Description: Execute custom commands and collect their output as facts

Required Fields:

base (BaseCollector): No description available
command (String): Command to execute
env (HashMap<String, String>): Environment variables
format (CommandOutputFormat): Expected output format
name (String): Collector name (used for metric names)
poll_interval (u64): Poll interval in seconds (how often to collect this metric)

Optional Fields:

cwd (Option): Working directory for command
enabled (bool): Whether this collector is enabled (default: true)
labels (HashMap<String, String>): Additional labels for this collector

Examples:

Basic command output collection:

YAML Format:

type: command
name: uptime
command: uptime -p
format: text
labels:
  category: system

JSON Format:

{
  "type": "command",
  "name": "uptime",
  "command": "uptime -p",
  "format": "text",
  "labels": {
    "category": "system"
  }
}

TOML Format:

[[collectors]]
type = "command"
name = "uptime"
command = "uptime -p"
format = "text"
[collectors.labels]
category = "system"

JSON command output parsing:

YAML Format:

type: command
name: docker_stats
command: docker stats --no-stream --format json
format: json
cwd: /tmp
env:
  DOCKER_HOST: unix:///var/run/docker.sock

JSON Format:

{
  "type": "command",
  "name": "docker_stats",
  "command": "docker stats --no-stream --format json",
  "format": "json",
  "cwd": "/tmp",
  "env": {
    "DOCKER_HOST": "unix:///var/run/docker.sock"
  }
}

TOML Format:

[[collectors]]
type = "command"
name = "docker_stats"
command = "docker stats --no-stream --format json"
format = "json"
cwd = "/tmp"
[collectors.env]
DOCKER_HOST = "unix:///var/run/docker.sock"

Output:

 command: "docker stats --no-stream --format json"
 exit_code: 0
 output:
   - container: "web_server"
     cpu_percent: "5.2"
     memory_usage: "128MiB / 1GiB"
     net_io: "1.2kB / 3.4kB"
   - container: "database"
     cpu_percent: "2.1"
     memory_usage: "256MiB / 2GiB"
     net_io: "500B / 1.2kB"
 labels:
   category: monitoring

Key-value command output parsing:

YAML Format:

type: command
name: system_info
command: echo "hostname=$(hostname)\nos_version=$(cat /etc/os-release | grep PRETTY_NAME | cut -d'=' -f2 | tr -d '\"')\nuptime=$(uptime -p)"
format: key_value
labels:
  category: system

JSON Format:

{
  "type": "command",
  "name": "system_info",
  "command": "echo \"hostname=$(hostname)\\nos_version=$(cat /etc/os-release | grep PRETTY_NAME | cut -d'=' -f2 | tr -d '\\\"')\\nuptime=$(uptime -p)\"",
  "format": "key_value",
  "labels": {
    "category": "system"
  }
}

TOML Format:

[[collectors]]
type = "command"
name = "system_info"
command = "echo \"hostname=$(hostname)\\nos_version=$(cat /etc/os-release | grep PRETTY_NAME | cut -d'=' -f2 | tr -d '\\\"')\\nuptime=$(uptime -p)\""
format = "key_value"
[collectors.labels]
category = "system"

Output:

 command: "echo \"hostname=$(hostname)\\nos_version=$(cat /etc/os-release | grep PRETTY_NAME | cut -d'=' -f2 | tr -d '\\\"')\\nuptime=$(uptime -p)\""
 exit_code: 0
 output:
   hostname: "web-server-01"
   os_version: "Ubuntu 22.04.3 LTS"
   uptime: "up 2 weeks, 3 days, 4 hours"
 labels:
   category: system

Text command output (default):

YAML Format:

type: command
name: disk_usage
command: df -h /
format: text
labels:
  category: storage

JSON Format:

{
  "type": "command",
  "name": "disk_usage",
  "command": "df -h /",
  "format": "text",
  "labels": {
    "category": "storage"
  }
}

TOML Format:

[[collectors]]
type = "command"
name = "disk_usage"
command = "df -h /"
format = "text"
[collectors.labels]
category = "storage"

Output:

 command: "df -h /"
 exit_code: 0
 stdout: |
   Filesystem      Size  Used Avail Use% Mounted on
   /dev/sda1        50G   15G   33G  31% /
 labels:
   category: storage

Command with environment variables and working directory:

YAML Format:

type: command
name: custom_script
command: ./check_service.sh
format: json
cwd: /opt/myapp
env:
  SERVICE_NAME: myapp
  LOG_LEVEL: info
labels:
  category: application

JSON Format:

{
  "type": "command",
  "name": "custom_script",
  "command": "./check_service.sh",
  "format": "json",
  "cwd": "/opt/myapp",
  "env": {
    "SERVICE_NAME": "myapp",
    "LOG_LEVEL": "info"
  },
  "labels": {
    "category": "application"
  }
}

TOML Format:

[[collectors]]
type = "command"
name = "custom_script"
command = "./check_service.sh"
format = "json"
cwd = "/opt/myapp"
[collectors.env]
SERVICE_NAME = "myapp"
LOG_LEVEL = "info"
[collectors.labels]
category = "application"

Output:

 command: "./check_service.sh"
 exit_code: 0
 output:
   service_status: "running"
   uptime_seconds: 3600
   version: "1.2.3"
   health_checks:
     - name: "database"
       status: "ok"
     - name: "cache"
       status: "ok"
 labels:
   category: application

Disk Metrics

disk

Description: Collect disk space and I/O statistics for mounted filesystems

Required Fields:

base (BaseCollector): No description available
collect (DiskCollectOptions): Disk metrics to collect
devices (Vec): Disk devices to monitor (empty = all)
mount_points (Vec): Mount points to monitor (empty = all)
name (String): Collector name (used for metric names)
poll_interval (u64): Poll interval in seconds (how often to collect this metric)
thresholds (DiskThresholds): Thresholds for alerts

Optional Fields:

enabled (bool): Whether this collector is enabled (default: true)
labels (HashMap<String, String>): Additional labels for this collector

Examples:

Basic disk metrics collection:

YAML Format:

type: disk
name: disk
devices: ["/dev/sda", "/dev/sdb"]
mount_points: ["/", "/home", "/var"]
collect:
  total: true
  used: true
  free: true
  available: true
  percentage: true
  io: true
thresholds:
  usage_warning: 80.0
  usage_critical: 90.0

JSON Format:

{
  "type": "disk",
  "name": "disk",
  "devices": ["/dev/sda", "/dev/sdb"],
  "mount_points": ["/", "/home", "/var"],
  "collect": {
    "total": true,
    "used": true,
    "free": true,
    "available": true,
    "percentage": true,
    "io": true
  },
  "thresholds": {
    "usage_warning": 80.0,
    "usage_critical": 90.0
  }
}

TOML Format:

[[collectors]]
type = "disk"
name = "disk"
devices = ["/dev/sda", "/dev/sdb"]
mount_points = ["/", "/home", "/var"]
[collectors.collect]
total = true
used = true
free = true
available = true
percentage = true
io = true
[collectors.thresholds]
usage_warning = 80.0
usage_critical = 90.0

Output:

 disks:
   - device: "/dev/sda1"
     mount_point: "/"
     is_removable: false
     total_bytes: 536870912000
     total_mb: 512000
     total_gb: 500
     used_bytes: 268435456000
     used_mb: 256000
     used_gb: 250
     free_bytes: 134217728000
     free_mb: 128000
     free_gb: 125
     available_bytes: 107374182400
     available_mb: 102400
     available_gb: 100
     usage_percent: 50
     available_percent: 20
     disk_pressure: "medium"
     usage_warning: false
     usage_critical: false
     io_supported: false
 labels:
   storage_type: ssd

Memory Metrics

memory

Description: Collect memory usage statistics including total, used, free, and swap

Required Fields:

base (BaseCollector): No description available
collect (MemoryCollectOptions): Memory metrics to collect
name (String): Collector name (used for metric names)
poll_interval (u64): Poll interval in seconds (how often to collect this metric)
thresholds (MemoryThresholds): Thresholds for alerts

Optional Fields:

enabled (bool): Whether this collector is enabled (default: true)
labels (HashMap<String, String>): Additional labels for this collector

Examples:

Basic memory metrics collection:

YAML Format:

type: memory
name: memory
collect:
  total: true
  used: true
  free: true
  available: true
  swap: true
  percentage: true
thresholds:
  usage_warning: 85.0
  usage_critical: 95.0

JSON Format:

{
  "type": "memory",
  "name": "memory",
  "collect": {
    "total": true,
    "used": true,
    "free": true,
    "available": true,
    "swap": true,
    "percentage": true
  },
  "thresholds": {
    "usage_warning": 85.0,
    "usage_critical": 95.0
  }
}

TOML Format:

[[collectors]]
type = "memory"
name = "memory"
[collectors.collect]
total = true
used = true
free = true
available = true
swap = true
percentage = true
[collectors.thresholds]
usage_warning = 85.0
usage_critical = 95.0

Output:

 total_bytes: 8589934592
 total_mb: 8192
 total_gb: 8
 used_bytes: 4294967296
 used_mb: 4096
 used_gb: 4
 free_bytes: 2147483648
 free_mb: 2048
 free_gb: 2
 available_bytes: 3221225472
 available_mb: 3072
 available_gb: 3
 usage_percent: 50
 available_percent: 37
 memory_pressure: "low"
 swap_total_bytes: 2147483648
 swap_used_bytes: 536870912
 swap_free_bytes: 1610612736
 swap_total_mb: 2048
 swap_used_mb: 512
 swap_free_mb: 1536
 swap_usage_percent: 25
 swap_pressure: "low"
 usage_warning: false
 usage_critical: false

Network Metrics

network

Description: Collect network interface statistics and status information

Required Fields:

base (BaseCollector): No description available
collect (NetworkCollectOptions): Network metrics to collect
interfaces (Vec): Network interfaces to monitor (empty = all)
name (String): Collector name (used for metric names)
poll_interval (u64): Poll interval in seconds (how often to collect this metric)

Optional Fields:

enabled (bool): Whether this collector is enabled (default: true)
labels (HashMap<String, String>): Additional labels for this collector

Examples:

Basic network metrics collection:

YAML Format:

type: network
name: network
interfaces: ["eth0", "wlan0"]
collect:
  bytes: true
  packets: true
  errors: true
  status: true

JSON Format:

{
  "type": "network",
  "name": "network",
  "interfaces": ["eth0", "wlan0"],
  "collect": {
    "bytes": true,
    "packets": true,
    "errors": true,
    "status": true
  }
}

TOML Format:

[[collectors]]
type = "network"
name = "network"
interfaces = ["eth0", "wlan0"]
[collectors.collect]
bytes = true
packets = true
errors = true
status = true

Output:

 interfaces:
   - name: "eth0"
     bytes_received: 1234567890
     bytes_transmitted: 987654321
     total_bytes: 2222222211
     packets_received: 1234567
     packets_transmitted: 987654
     total_packets: 2222221
     errors_on_received: 0
     errors_on_transmitted: 0
     total_errors: 0
     status: "up"
   - name: "lo"
     bytes_received: 123456789
     bytes_transmitted: 123456789
     total_bytes: 246913578
     packets_received: 123456
     packets_transmitted: 123456
     total_packets: 246912
     errors_on_received: 0
     errors_on_transmitted: 0
     total_errors: 0
     status: "up"
 labels:
   network_type: corporate

Process Metrics

process

Description: Collect process information and resource usage statistics

Required Fields:

base (BaseCollector): No description available
collect (ProcessCollectOptions): Process metrics to collect
name (String): Collector name (used for metric names)
patterns (Vec): Process name patterns to monitor (empty = all processes)
poll_interval (u64): Poll interval in seconds (how often to collect this metric)

Optional Fields:

enabled (bool): Whether this collector is enabled (default: true)
labels (HashMap<String, String>): Additional labels for this collector

Examples:

Basic process metrics collection:

YAML Format:

type: process
name: process
patterns: ["nginx", "apache", "sshd"]
collect:
  count: true
  cpu: true
  memory: true
  status: true

JSON Format:

{
  "type": "process",
  "name": "process",
  "patterns": ["nginx", "apache", "sshd"],
  "collect": {
    "count": true,
    "cpu": true,
    "memory": true,
    "status": true
  }
}

TOML Format:

[[collectors]]
type = "process"
name = "process"
patterns = ["nginx", "apache", "sshd"]
[collectors.collect]
count = true
cpu = true
memory = true
status = true

Output:

 total_processes: 150
 matched_processes: 3
 processes:
   - pid: 1234
     name: "nginx"
     cpu_percent: 5
     memory_bytes: 104857600
     memory_mb: 100
     memory_gb: 0
     status: "running"
     command: "/usr/sbin/nginx"
     parent_pid: 1
   - pid: 1235
     name: "nginx"
     cpu_percent: 3
     memory_bytes: 52428800
     memory_mb: 50
     memory_gb: 0
     status: "running"
     command: "/usr/sbin/nginx"
     parent_pid: 1234
   - pid: 5678
     name: "apache2"
     cpu_percent: 2
     memory_bytes: 209715200
     memory_mb: 200
     memory_gb: 0
     status: "sleeping"
     command: "/usr/sbin/apache2"
     parent_pid: 1
 labels:
   process_type: web_servers

System Information

system

Description: Collect system information including hostname, OS, kernel, uptime, and architecture

Required Fields:

base (BaseCollector): No description available
collect (SystemCollectOptions): What system information to collect
name (String): Collector name (used for metric names)
poll_interval (u64): Poll interval in seconds (how often to collect this metric)

Optional Fields:

enabled (bool): Whether this collector is enabled (default: true)
labels (HashMap<String, String>): Additional labels for this collector

Examples:

Basic system information collection:

YAML Format:

type: system
name: system
collect:
  hostname: true
  os: true
  kernel: true
  uptime: true
  boot_time: true
  arch: true

JSON Format:

{
  "type": "system",
  "name": "system",
  "collect": {
    "hostname": true,
    "os": true,
    "kernel": true,
    "uptime": true,
    "boot_time": true,
    "arch": true
  }
}

TOML Format:

[[collectors]]
type = "system"
name = "system"
[collectors.collect]
hostname = true
os = true
kernel = true
uptime = true
boot_time = true
arch = true

Output:

 hostname: "myhost.example.com"
 os: "linux"
 os_family: "unix"
 kernel_version: "5.15.0-91-generic"
 uptime_seconds: 1234567
 boot_time: 1706012345
 cpu_arch: "x86_64"

Log Sources/Outputs (`logs`)

Log processors handle log collection and forwarding. Each processor corresponds to a specific log source or output destination.

Processor Configuration

All log processors support common configuration fields for controlling processing behavior:

enabled: Whether this processor is enabled (default: true)
name: Processor name for identification

Log Outputs

console

Description: Output logs to stdout/stderr for debugging

Required Fields:

name (String): Processor name for identification

Optional Fields:

enabled (bool): Whether this processor is enabled (default: true)

Examples:

File log output:

YAML Format:

logs:
  - type: file
    path: /var/log/app.log
    format: json
    rotation:
      size: 10MB
      count: 5

JSON Format:

{
  "logs": [
    {
      "type": "file",
      "path": "/var/log/app.log",
      "format": "json",
      "rotation": {
        "size": "10MB",
        "count": 5
      }
    }
  ]
}

TOML Format:

[[logs]]
type = "file"
path = "/var/log/app.log"
format = "json"
[logs.rotation]
size = "10MB"
count = 5

Console log output:

YAML Format:

logs:
  - type: console
    format: text
    level: info

JSON Format:

{
  "logs": [
    {
      "type": "console",
      "format": "text",
      "level": "info"
    }
  ]
}

TOML Format:

[[logs]]
type = "console"
format = "text"
level = "info"

Syslog log output:

YAML Format:

logs:
  - type: syslog
    facility: local0
    severity: info
    tag: driftless
    server: 127.0.0.1:514
    protocol: udp

JSON Format:

{
  "logs": [
    {
      "type": "syslog",
      "facility": "local0",
      "severity": "info",
      "tag": "driftless",
      "server": "127.0.0.1:514",
      "protocol": "udp"
    }
  ]
}

TOML Format:

[[logs]]
type = "syslog"
facility = "local0"
severity = "info"
tag = "driftless"
server = "127.0.0.1:514"
protocol = "udp"

file

Description: Write logs to files with rotation and compression

Required Fields:

name (String): Processor name for identification

Optional Fields:

enabled (bool): Whether this processor is enabled (default: true)

Examples:

File log output:

YAML Format:

logs:
  - type: file
    path: /var/log/app.log
    format: json
    rotation:
      size: 10MB
      count: 5

JSON Format:

{
  "logs": [
    {
      "type": "file",
      "path": "/var/log/app.log",
      "format": "json",
      "rotation": {
        "size": "10MB",
        "count": 5
      }
    }
  ]
}

TOML Format:

[[logs]]
type = "file"
path = "/var/log/app.log"
format = "json"
[logs.rotation]
size = "10MB"
count = 5

Console log output:

YAML Format:

logs:
  - type: console
    format: text
    level: info

JSON Format:

{
  "logs": [
    {
      "type": "console",
      "format": "text",
      "level": "info"
    }
  ]
}

TOML Format:

[[logs]]
type = "console"
format = "text"
level = "info"

Syslog log output:

YAML Format:

logs:
  - type: syslog
    facility: local0
    severity: info
    tag: driftless
    server: 127.0.0.1:514
    protocol: udp

JSON Format:

{
  "logs": [
    {
      "type": "syslog",
      "facility": "local0",
      "severity": "info",
      "tag": "driftless",
      "server": "127.0.0.1:514",
      "protocol": "udp"
    }
  ]
}

TOML Format:

[[logs]]
type = "syslog"
facility = "local0"
severity = "info"
tag = "driftless"
server = "127.0.0.1:514"
protocol = "udp"

http

Description: Send logs to HTTP endpoints with authentication and retry

Required Fields:

name (String): Processor name for identification

Optional Fields:

enabled (bool): Whether this processor is enabled (default: true)

Examples:

File log output:

YAML Format:

logs:
  - type: file
    path: /var/log/app.log
    format: json
    rotation:
      size: 10MB
      count: 5

JSON Format:

{
  "logs": [
    {
      "type": "file",
      "path": "/var/log/app.log",
      "format": "json",
      "rotation": {
        "size": "10MB",
        "count": 5
      }
    }
  ]
}

TOML Format:

[[logs]]
type = "file"
path = "/var/log/app.log"
format = "json"
[logs.rotation]
size = "10MB"
count = 5

Console log output:

YAML Format:

logs:
  - type: console
    format: text
    level: info

JSON Format:

{
  "logs": [
    {
      "type": "console",
      "format": "text",
      "level": "info"
    }
  ]
}

TOML Format:

[[logs]]
type = "console"
format = "text"
level = "info"

Syslog log output:

YAML Format:

logs:
  - type: syslog
    facility: local0
    severity: info
    tag: driftless
    server: 127.0.0.1:514
    protocol: udp

JSON Format:

{
  "logs": [
    {
      "type": "syslog",
      "facility": "local0",
      "severity": "info",
      "tag": "driftless",
      "server": "127.0.0.1:514",
      "protocol": "udp"
    }
  ]
}

TOML Format:

[[logs]]
type = "syslog"
facility = "local0"
severity = "info"
tag = "driftless"
server = "127.0.0.1:514"
protocol = "udp"

s3

Description: Upload logs to S3 with batching and compression

Required Fields:

name (String): Processor name for identification

Optional Fields:

enabled (bool): Whether this processor is enabled (default: true)

Examples:

File log output:

YAML Format:

logs:
  - type: file
    path: /var/log/app.log
    format: json
    rotation:
      size: 10MB
      count: 5

JSON Format:

{
  "logs": [
    {
      "type": "file",
      "path": "/var/log/app.log",
      "format": "json",
      "rotation": {
        "size": "10MB",
        "count": 5
      }
    }
  ]
}

TOML Format:

[[logs]]
type = "file"
path = "/var/log/app.log"
format = "json"
[logs.rotation]
size = "10MB"
count = 5

Console log output:

YAML Format:

logs:
  - type: console
    format: text
    level: info

JSON Format:

{
  "logs": [
    {
      "type": "console",
      "format": "text",
      "level": "info"
    }
  ]
}

TOML Format:

[[logs]]
type = "console"
format = "text"
level = "info"

Syslog log output:

YAML Format:

logs:
  - type: syslog
    facility: local0
    severity: info
    tag: driftless
    server: 127.0.0.1:514
    protocol: udp

JSON Format:

{
  "logs": [
    {
      "type": "syslog",
      "facility": "local0",
      "severity": "info",
      "tag": "driftless",
      "server": "127.0.0.1:514",
      "protocol": "udp"
    }
  ]
}

TOML Format:

[[logs]]
type = "syslog"
facility = "local0"
severity = "info"
tag = "driftless"
server = "127.0.0.1:514"
protocol = "udp"

syslog

Description: Send logs to syslog with RFC compliance

Required Fields:

name (String): Processor name for identification

Optional Fields:

enabled (bool): Whether this processor is enabled (default: true)

Examples:

File log output:

YAML Format:

logs:
  - type: file
    path: /var/log/app.log
    format: json
    rotation:
      size: 10MB
      count: 5

JSON Format:

{
  "logs": [
    {
      "type": "file",
      "path": "/var/log/app.log",
      "format": "json",
      "rotation": {
        "size": "10MB",
        "count": 5
      }
    }
  ]
}

TOML Format:

[[logs]]
type = "file"
path = "/var/log/app.log"
format = "json"
[logs.rotation]
size = "10MB"
count = 5

Console log output:

YAML Format:

logs:
  - type: console
    format: text
    level: info

JSON Format:

{
  "logs": [
    {
      "type": "console",
      "format": "text",
      "level": "info"
    }
  ]
}

TOML Format:

[[logs]]
type = "console"
format = "text"
level = "info"

Syslog log output:

YAML Format:

logs:
  - type: syslog
    facility: local0
    severity: info
    tag: driftless
    server: 127.0.0.1:514
    protocol: udp

JSON Format:

{
  "logs": [
    {
      "type": "syslog",
      "facility": "local0",
      "severity": "info",
      "tag": "driftless",
      "server": "127.0.0.1:514",
      "protocol": "udp"
    }
  ]
}

TOML Format:

[[logs]]
type = "syslog"
facility = "local0"
severity = "info"
tag = "driftless"
server = "127.0.0.1:514"
protocol = "udp"

Comprehensive Examples

This section provides complete examples showing how to use Driftless for common configuration management tasks.

Complete Configuration Example

Here’s a complete example showing a typical web server setup:

YAML Format:

vars:
  web_user: www-data
  web_root: /var/www/html
  nginx_config: /etc/nginx/sites-available/default

tasks:
  # Install required packages
  - type: package
    name: nginx
    state: present

  # Create web directory
  - type: file
    path: "{{ web_root }}"
    state: present
    mode: "0755"
    owner: "{{ web_user }}"
    group: "{{ web_user }}"

  # Configure nginx
  - type: file
    path: "{{ nginx_config }}"
    state: present
    content: |
      server {
          listen 80;
          root {{ web_root }};
          index index.html index.htm;

          location / {
              try_files $uri $uri/ =404;
          }
      }
    mode: "0644"
    owner: root
    group: root

  # Create index page
  - type: file
    path: "{{ web_root }}/index.html"
    state: present
    content: |
      <!DOCTYPE html>
      <html>
      <head><title>Welcome to Driftless</title></head>
      <body><h1>Hello from Driftless!</h1></body>
      </html>
    mode: "0644"
    owner: "{{ web_user }}"
    group: "{{ web_user }}"

  # Start and enable nginx service
  - type: service
    name: nginx
    state: started
    enabled: true

JSON Format:

{
  "vars": {
    "web_user": "www-data",
    "web_root": "/var/www/html",
    "nginx_config": "/etc/nginx/sites-available/default"
  },
  "tasks": [
    {
      "type": "package",
      "name": "nginx",
      "state": "present"
    },
    {
      "type": "file",
      "path": "{{ web_root }}",
      "state": "present",
      "mode": "0755",
      "owner": "{{ web_user }}",
      "group": "{{ web_user }}"
    },
    {
      "type": "file",
      "path": "{{ nginx_config }}",
      "state": "present",
      "content": "server {\n    listen 80;\n    root {{ web_root }};\n    index index.html index.htm;\n\n    location / {\n        try_files $uri $uri/ =404;\n    }\n}",
      "mode": "0644",
      "owner": "root",
      "group": "root"
    },
    {
      "type": "file",
      "path": "{{ web_root }}/index.html",
      "state": "present",
      "content": "<!DOCTYPE html>\n<html>\n<head><title>Welcome to Driftless</title></head>\n<body><h1>Hello from Driftless!</h1></body>\n</html>",
      "mode": "0644",
      "owner": "{{ web_user }}",
      "group": "{{ web_user }}"
    },
    {
      "type": "service",
      "name": "nginx",
      "state": "started",
      "enabled": true
    }
  ]
}

TOML Format:

[vars]
web_user = "www-data"
web_root = "/var/www/html"
nginx_config = "/etc/nginx/sites-available/default"

[[tasks]]
type = "package"
name = "nginx"
state = "present"

[[tasks]]
type = "file"
path = "{{ web_root }}"
state = "present"
mode = "0755"
owner = "{{ web_user }}"
group = "{{ web_user }}"

[[tasks]]
type = "file"
path = "{{ nginx_config }}"
state = "present"
content = """
server {
    listen 80;
    root {{ web_root }};
    index index.html index.htm;

    location / {
    try_files $uri $uri/ =404;
    }
}
"""
mode = "0644"
owner = "root"
group = "root"

[[tasks]]
type = "file"
path = "{{ web_root }}/index.html"
state = "present"
content = """
<!DOCTYPE html>
<html>
<head><title>Welcome to Driftless</title></head>
<body><h1>Hello from Driftless!</h1></body>
</html>
"""
mode = "0644"
owner = "{{ web_user }}"
group = "{{ web_user }}"

[[tasks]]
type = "service"
name = "nginx"
state = "started"
enabled = true

Keyboard shortcuts

Driftless Documentation