Posix Provider

This document describes the implementation details of the Posix exec provider for executing commands without a shell.

Provider Selection

The Posix provider is the default exec provider. It is always available and returns priority 1 for all exec resources unless a different provider is explicitly requested via the provider property.

To use the shell provider instead, specify provider: shell in the resource properties.

Comparison with Shell Provider

When to use Posix (default):

• Simple commands with arguments
• When shell features are not needed
• For better security (no shell injection risk)

When to use Shell:

• Commands with pipes, redirections, or shell builtins
• Complex command strings
• When shell expansion is required

Operations

Execute

Process:

1. Determine command source (Command property or Name if Command is empty)
2. Parse command string into words using shellquote.Split()
3. Extract command (first word) and arguments (remaining words)
4. Execute via CommandRunner.ExecuteWithOptions()
5. Optionally log output line-by-line if LogOutput is enabled

Command Parsing:

The command string is parsed using github.com/kballard/go-shellquote, which handles:

Execution Options:

Output Logging:

When LogOutput: true is set and a user logger is provided:

scanner := bufio.NewScanner(bytes.NewReader(stdout))
for scanner.Scan() {
    log.Info(scanner.Text())
}

Each line of stdout is logged as a separate Info message.

Error Handling:

EvaluateGuard

Process:

1. Parse guard command string into words using shellquote.Split()
2. Extract command (first word) and arguments (remaining words)
3. Execute via CommandRunner.ExecuteWithOptions() using the same cwd, environment, path, and timeout from the exec properties
4. Return true if exit code is 0, false if non-zero

Error Handling:

Status

Process:

1. Create state with EnsurePresent (exec resources are always “present”)
2. Check if Creates file exists via util.FileExists()
3. Set CreatesSatisfied accordingly

State Fields:

Idempotency

The exec resource achieves idempotency through multiple mechanisms:

Creates File

If creates is specified and the file exists, the command does not run:

- exec:
    - /usr/bin/tar -xzf app.tar.gz:
        creates: /opt/app/bin/app
        cwd: /opt

Guard Commands

If onlyif is specified, the command only runs when the guard exits 0. If unless is specified, the command only runs when the guard exits non-zero:

- exec:
    - install-app:
        command: /usr/local/bin/install-app.sh
        onlyif: test -f /tmp/app-package.tar.gz

    - configure-firewall:
        command: /usr/sbin/iptables -A INPUT -p tcp --dport 8080 -j ACCEPT
        unless: /usr/sbin/iptables -C INPUT -p tcp --dport 8080 -j ACCEPT

RefreshOnly Mode

When refreshonly: true, the command only runs when triggered by a subscribed resource:

- exec:
    - systemctl reload httpd:
        refreshonly: true
        subscribe:
          - file#/etc/httpd/conf/httpd.conf

Exit Code Validation

The returns property specifies acceptable exit codes (default: [0]):

- exec:
    - /opt/app/healthcheck:
        returns: [0, 1, 2]  # 0=healthy, 1=degraded, 2=warning

Decision Flow

┌─────────────────────────────────────────┐
│ Should resource be applied?             │
└─────────────────┬───────────────────────┘
                  │
                  ▼
┌─────────────────────────────────────────┐
│ Subscribe triggered?                     │
│ (subscribed resource changed)            │
└─────────────┬───────────────┬───────────┘
              │ Yes           │ No
              ▼               ▼
┌─────────────────┐   ┌───────────────────┐
│ Execute command │   │ Creates satisfied? │
└─────────────────┘   └─────────┬─────────┘
                                │
                      ┌─────────┴─────────┐
                      │ Yes               │ No
                      ▼                   ▼
              ┌───────────────┐   ┌───────────────────────┐
              │ Skip (stable) │   │ Guard commands pass?  │
              └───────────────┘   │ (onlyif=0, unless≠0) │
                                  └─────────┬─────────────┘
                                            │
                                  ┌─────────┴─────────┐
                                  │ No                │ Yes
                                  ▼                   ▼
                          ┌───────────────┐   ┌───────────────────┐
                          │ Skip (stable) │   │ RefreshOnly mode? │
                          └───────────────┘   └─────────┬─────────┘
                                                        │
                                              ┌─────────┴─────────┐
                                              │ Yes               │ No
                                              ▼                   ▼
                                      ┌───────────────┐   ┌───────────────┐
                                      │ Skip (stable) │   │ Execute       │
                                      └───────────────┘   └───────────────┘

Properties Validation

The model validates exec properties before execution:

Platform Support

The Posix provider works on all platforms supported by Go’s os/exec package. It does not use any platform-specific system calls directly.

The command runner (model.CommandRunner) handles the actual process execution, which may have platform-specific implementations.

Security Considerations

No Shell Injection

Unlike the shell provider, the posix provider does not invoke a shell. Arguments are passed directly to the executable, preventing shell injection attacks:

# Safe with posix provider - $USER is passed literally, not expanded
- exec:
    - /bin/echo $USER:
        provider: posix  # Default

# Potentially dangerous with shell provider - $USER is expanded
- exec:
    - /bin/echo $USER:
        provider: shell

Path Validation

The path property only accepts absolute directory paths, preventing path traversal via relative paths.

Environment Validation

Environment variables must have non-empty keys and values, preventing injection of empty or malformed entries.

Shell Provider

This document describes the implementation details of the Shell exec provider for executing commands via /bin/sh.

Provider Selection

The Shell provider is selected when provider: shell is explicitly specified in the resource properties. It has a lower priority (99) than the Posix provider (1), so it is never automatically selected.

Availability: The provider checks for the existence of /bin/sh via util.FileExists(). If /bin/sh does not exist, the provider is not available.

Comparison with Posix Provider

When to use Shell:

• Commands with pipes: cat file.txt | grep pattern | sort
• Commands with redirections: echo "data" > /tmp/file
• Commands with shell builtins: cd /tmp && pwd
• Commands with variable expansion: echo $HOME
• Complex one-liners with logical operators

When to use Posix (default):

• Simple commands with arguments
• When shell features are not needed
• For better security (no shell injection risk)

Operations

Execute

Process:

1. Determine command source (Command property or Name if Command is empty)
2. Validate command is not empty
3. Execute via CommandRunner.ExecuteWithOptions() with /bin/sh -c "<command>"
4. Optionally log output line-by-line if LogOutput is enabled

Execution Method:

The entire command string is passed to the shell as a single argument:

/bin/sh -c "<entire command string>"

This allows the shell to interpret all shell syntax, including:

• Pipes and redirections
• Variable expansion
• Glob patterns
• Command substitution
• Logical operators

Execution Options:

Output Logging:

When LogOutput: true is set and a user logger is provided:

scanner := bufio.NewScanner(bytes.NewReader(stdout))
for scanner.Scan() {
    log.Info(scanner.Text())
}

Each line of stdout is logged as a separate Info message.

Error Handling:

EvaluateGuard

Process:

1. Validate command is not empty
2. Execute via CommandRunner.ExecuteWithOptions() with /bin/sh -c "<command>" using the same cwd, environment, path, and timeout from the exec properties
3. Return true if exit code is 0, false if non-zero

The shell provider is well-suited for guard commands that use shell features:

- exec:
    - add-repo:
        command: /usr/bin/add-apt-repository ppa:example/ppa
        provider: shell
        unless: grep -q example /etc/apt/sources.list.d/*.list

Error Handling:

Status

Process:

1. Create state with EnsurePresent (exec resources are always “present”)
2. Check if Creates file exists via util.FileExists()
3. Set CreatesSatisfied accordingly

State Fields:

Use Cases

Pipes and Filters

- exec:
    - filter-logs:
        command: cat /var/log/app.log | grep ERROR | tail -100 > /tmp/errors.txt
        provider: shell
        creates: /tmp/errors.txt

Conditional Execution

- exec:
    - ensure-running:
        command: pgrep myapp || /opt/myapp/bin/start
        provider: shell

Complex Scripts

- exec:
    - deploy-app:
        command: |
          cd /opt/app &&
          git pull origin main &&
          npm install &&
          npm run build &&
          systemctl restart app
        provider: shell
        timeout: 5m

Variable Expansion

- exec:
    - backup-home:
        command: tar -czf /backup/home-$(date +%Y%m%d).tar.gz $HOME
        provider: shell

Idempotency

The shell provider uses the same idempotency mechanisms as the posix provider:

Creates File

If creates is specified and the file exists, the command does not run:

- exec:
    - extract-archive:
        command: cd /opt && tar -xzf /tmp/app.tar.gz
        provider: shell
        creates: /opt/app/bin/app

Guard Commands

If onlyif is specified, the command only runs when the guard exits 0. If unless is specified, the command only runs when the guard exits non-zero. Guard commands are executed via /bin/sh -c and can use shell features:

- exec:
    - configure-firewall:
        command: /usr/sbin/iptables -A INPUT -p tcp --dport 8080 -j ACCEPT
        provider: shell
        unless: /usr/sbin/iptables -C INPUT -p tcp --dport 8080 -j ACCEPT 2>/dev/null

RefreshOnly Mode

When refreshonly: true, the command only runs when triggered by a subscribed resource:

- exec:
    - reload-nginx:
        command: nginx -t && systemctl reload nginx
        provider: shell
        refreshonly: true
        subscribe:
          - file#/etc/nginx/nginx.conf

Exit Code Validation

The returns property specifies acceptable exit codes (default: [0]):

- exec:
    - check-service:
        command: systemctl is-active myapp || true
        provider: shell
        returns: [0]

Security Considerations

Shell Injection Risk

The shell provider passes the command string directly to /bin/sh, making it vulnerable to shell injection if user input is incorporated:

# DANGEROUS if filename comes from untrusted input
- exec:
    - process-file:
        command: cat {{ user_provided_filename }} | process
        provider: shell

Mitigations:

• Validate and sanitize any templated values
• Use the posix provider when shell features aren’t needed
• Prefer explicit file paths over user-provided values

Environment Variable Exposure

Shell commands can access environment variables, including sensitive ones:

# $SECRET_KEY will be expanded by the shell
- exec:
    - use-secret:
        command: myapp --key=$SECRET_KEY
        provider: shell

Consider using the environment property to explicitly pass required variables rather than relying on inherited environment.

Command Logging

The full command string (including any expanded variables) may appear in logs. Avoid embedding secrets directly in commands:

# BAD - password visible in logs
- exec:
    - bad-example:
        command: mysql -p'secret123' -e 'SELECT 1'
        provider: shell

# BETTER - use environment variable
- exec:
    - better-example:
        command: mysql -p"$MYSQL_PWD" -e 'SELECT 1'
        provider: shell
        environment:
          - MYSQL_PWD={{ lookup('data.mysql_password') }}

Platform Support

The shell provider requires /bin/sh to be available. This is standard on:

• Linux distributions
• macOS
• BSD variants
• Most Unix-like systems

On Windows, the provider will not be available unless /bin/sh exists (e.g., via WSL or Cygwin).

Shell Compatibility

The provider uses /bin/sh, which is typically:

• Linux: Often a symlink to bash, dash, or another POSIX-compliant shell
• macOS: /bin/sh is bash (older) or zsh (newer) in POSIX mode
• BSD: Usually ash or similar

For maximum portability, use POSIX shell syntax and avoid bash-specific features like:

• Arrays (arr=(1 2 3))
• [[ conditionals (use [ instead)
• source (use . instead)
• Process substitution (<(command))