HTTP Provider

This document describes the implementation details of the HTTP archive provider for downloading and extracting archives from HTTP/HTTPS URLs.

Provider Selection

The HTTP provider is selected when:

1. The URL scheme is http or https
2. The archive file extension is supported (.tar.gz, .tgz, .tar, .zip)
3. The required extraction tool (tar or unzip) is available in PATH

The IsManageable() function checks these conditions and returns a priority of 1 if all are met.

Operations

Download

Process:

1. Parse the URL and add Basic Auth credentials if username/password provided
2. Create HTTP request with custom headers (if specified)
3. Execute GET request via util.HttpGetResponse()
4. Verify HTTP 200 status code
5. Create temporary file in the same directory as the target
6. Set ownership on temp file before writing content
7. Copy response body to temp file
8. Verify checksum if provided
9. Atomic rename temp file to target path

Atomic Write Pattern:

[parent dir]/archive-name-* (temp file)
    ↓ write content
    ↓ set owner/group
    ↓ verify checksum
    ↓ rename
[parent dir]/archive-name (final file)

The temp file is created in the same directory as the target to ensure os.Rename() is atomic (same filesystem).

Error Handling:

Authentication:

Extract

Process:

1. Validate ExtractParent is set
2. Create ExtractParent directory if it doesn’t exist (mode 0755)
3. Determine archive type from file extension
4. Execute appropriate extraction command

Extraction Commands:

Command Execution:

Commands are executed via model.CommandRunner.ExecuteWithOptions() with:

Error Handling:

Status

Process:

1. Initialize state with EnsureAbsent default
2. Check if archive file exists via os.Stat()
3. If exists: set EnsurePresent, populate metadata (size, mtime, owner, group, checksum)
4. If Creates property set: check if creates file exists

Metadata Collected:

Idempotency

The provider supports idempotency through the type’s isDesiredState() function:

State Checks (in order)

1. Ensure Absent: If ensure: absent, archive must not exist
2. Creates File: If Creates set and file doesn’t exist → not stable
3. Archive Existence: If cleanup: false, archive must exist
4. Owner/Group: Must match properties
5. Checksum: If specified in properties, must match

Note: When cleanup: true, the creates property is required (enforced at validation time).

Decision Matrix

Checksum Verification

Algorithm: SHA-256

Implementation:

sum, err := util.Sha256HashFile(tempFile)
if sum != properties.Checksum {
    return fmt.Errorf("checksum mismatch, expected %q got %q", properties.Checksum, sum)
}

Timing: Checksum is verified after download completes but before the atomic rename. This ensures:

• Corrupted downloads are never placed at the target path
• Temp file is cleaned up on mismatch
• Clear error message with both expected and actual checksums

Security Considerations

Credential Handling

• Credentials in URL are redacted in log messages via util.RedactUrlCredentials()
• Basic Auth header is set by Go’s http.Request.SetBasicAuth(), not manually constructed

Archive Extraction

• Extraction uses system tar/unzip commands
• No path traversal protection beyond what the tools provide
• ExtractParent must be an absolute path (validated in model)

Temporary Files

• Created with os.CreateTemp() using pattern <archive-name>-*
• Deferred removal ensures cleanup on all exit paths
• Ownership set before content written

Platform Support

The provider is Unix-only due to:

• Dependency on util.GetFileOwner() which uses syscall for UID/GID resolution
• Dependency on util.ChownFile() for ownership management

Timeouts

Large archives may require increased timeouts in future versions.

CCM Manifest Provider

This document describes the implementation details of the CCM Manifest provider for resolving and executing child manifests.

Provider Selection

The CCM Manifest provider is the only apply provider. It is always available and returns priority 1 for all apply resources.

Operations

ApplyManifest

Process:

1. Capture parent state (noop mode, working directory, data)
2. Strengthen noop mode if the parent is in noop mode or the resource has noop: true
3. Build execution options for the child manifest
4. Resolve the child manifest via apply.ResolveManifestUrl()
5. Execute the resolved manifest via resolvedApply.Execute()
6. Inspect child resource outcomes (changed, failed, skipped)
7. Restore parent state via deferred restore

Noop Strengthening:

The provider only strengthens noop mode, never weakens it. If the parent manager is already in noop mode, the child inherits that regardless of its own noop property. If the parent is not in noop mode and the resource sets noop: true, the provider enables noop on the manager before resolution.

Health check mode follows the same strengthening pattern. The effective health check mode is true if either the parent or the resource sets it.

Execute Options:

The provider builds these options to control child manifest behavior:

State Capture and Restore

The provider saves three pieces of manager state before manifest resolution and restores them after execution via defer. This ensures restoration runs even if resolution or execution fails.

State capture happens before any resolve or mutation calls. This ordering is critical because ResolveManifestUrl mutates the manager’s working directory and data during resolution.

Restoration ensures that subsequent resources in the parent manifest see the original manager state. Without it, a child manifest’s working directory and data changes would leak into sibling resources.

Path Resolution

The resource name property specifies a file path relative to the parent manifest’s directory. During resolution, ResolveManifestFilePath joins relative paths with the manager’s current working directory before opening the file.

For nested apply resources, each level sets the working directory to its own manifest’s parent directory. The state restore ensures the working directory returns to the correct value after each child completes.

/opt/ccm/manifest.yaml          WD = /opt/ccm/
  apply: sub/manifest.yaml       resolves to /opt/ccm/sub/manifest.yaml
                                  WD = /opt/ccm/sub/
    apply: lib/manifest.yaml     resolves to /opt/ccm/sub/lib/manifest.yaml
                                  WD = /opt/ccm/sub/lib/
                                  (restore WD to /opt/ccm/sub/)
                                (restore WD to /opt/ccm/)

Child Resource Inspection

After execution, the provider iterates over child resources to count outcomes using the shared session:

The provider builds an ApplyState with the total resource count and reports the outcome:

Logging

The provider creates a child user logger with a manifest key set to the resource name. All child resource log output includes this key, providing attribution for which parent apply resource triggered the execution.

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))

Posix Provider

This document describes the implementation details of the Posix file provider for managing files and directories on Unix-like systems.

Provider Selection

The Posix provider is the default and only file provider. It is always available and returns priority 1 for all file resources.

Operations

Store (Create/Update File)

Process:

1. Verify parent directory exists
2. Parse file mode from octal string
3. Open source file if source property is set
4. Create temporary file in the same directory as target
5. Set file permissions on temp file
6. Write content (from source file or contents property)
7. Set ownership (chown) on temp file
8. Close temp file
9. Atomic rename temp file to target path

Atomic Write Pattern:

[parent dir]/<basename>.* (temp file)
    ↓ chmod (set permissions)
    ↓ write content
    ↓ chown (set owner/group)
    ↓ close
    ↓ rename
[parent dir]/<basename> (final file)

The temp file is created in the same directory as the target to ensure os.Rename() is atomic (same filesystem).

Content Sources:

If both are empty, an empty file is created.

Error Handling:

CreateDirectory

Process:

1. Parse file mode from octal string
2. Create directory and parents via os.MkdirAll()
3. Lookup numeric UID/GID from owner/group names
4. Set permissions via os.Chmod() (ensures correct mode even if umask affected MkdirAll)
5. Set ownership via os.Chown()

Command Sequence:

os.MkdirAll(dir, parsedMode)    // Create directory tree
os.Chmod(dir, parsedMode)        // Ensure correct permissions
os.Chown(dir, uid, gid)          // Set ownership

The explicit Chmod after MkdirAll is necessary because MkdirAll applies the process umask to the mode.

Remove

Process:

• When force is true, the path is removed with os.RemoveAll().
• When force is false, the path is removed with os.Remove().
• A path that does not exist is treated as a no-op (no error).
• When os.Remove() fails with syscall.ENOTEMPTY, the error is wrapped with guidance pointing the user at force: true.

Error Handling:

Symlink Behavior:

os.RemoveAll() does not follow symlinks during traversal. If the target path is itself a symlink, only the symlink is removed and its target is left intact. A directory tree that contains symlinks to external locations is safe to remove with force: true: the symlink entries are unlinked, but the directories they point to are not deleted.

Context Cancellation:

os.RemoveAll() does not observe ctx. Removal of a very large tree cannot be interrupted mid-walk. This is acceptable for typical CCM workloads but should be considered when scheduling removal of large directories.

Status

Process:

1. Initialize state with default metadata
2. Call os.Stat() on file path
3. Based on result, populate state accordingly

State Detection:

Metadata Collection:

Note: Checksum is only calculated for regular files, not directories.

Idempotency

The file resource achieves idempotency by comparing current state against desired state:

State Checks

The isDesiredState() function checks (in order):

1. Ensure value matches - present, absent, or directory
2. Content checksum matches - SHA256 of contents vs existing file (for files only)
3. Owner matches - Owner comparison, normalized through util.UserIDMatches so a manifest written with a numeric UID compares equal to a named user with the same UID, and vice versa
4. Group matches - Group comparison, normalized through util.GroupIDMatches using the same rules
5. Mode matches - Octal permission string comparison

Decision Flow

┌─────────────────────────────────────────┐
│ What is the desired ensure state?       │
└─────────────────┬───────────────────────┘
                  │
    ┌─────────────┼─────────────┬─────────────┐
    │ absent      │ directory   │ present     │
    ▼             ▼             ▼             │
┌───────────┐ ┌───────────┐ ┌───────────────┐ │
│ File      │ │ Directory │ │ File exists?  │ │
│ exists?   │ │ exists?   │ │ Content match?│ │
└─────┬─────┘ └─────┬─────┘ │ Owner match?  │ │
      │             │       │ Group match?  │ │
  Yes │ No      Yes │ No    │ Mode match?   │ │
      ▼             ▼       └───────┬───────┘ │
┌─────────┐ ┌───────────┐           │         │
│ Remove  │ │ Stable    │     All Yes│    No   │
│ file    │ │           │           ▼         ▼
└─────────┘ └───────────┘   ┌───────────┐ ┌───────────┐
                            │ Stable    │ │ Store     │
                            └───────────┘ └───────────┘

Content Comparison

For files with ensure: present:

The source path is adjusted based on the manager’s working directory when set.

Mode Validation

File modes are validated during resource creation:

1. Strip optional 0o or 0O prefix
2. Parse as octal number (base 8)
3. Validate range: must be ≤ 0777

Valid Mode Examples:

Invalid Mode Examples:

Ownership Resolution

Owner and group values are resolved to numeric UID/GID via:

uid, gid, err := util.LookupOwnerGroup(owner, group)

Resolution depends on the value’s form:

• A purely-numeric value (digits only) is parsed directly as a UID or GID. The system user database is not consulted, matching the semantics of chown(1) when given a numeric argument.
• Any other value is resolved through the system user database (/etc/passwd, /etc/group, or equivalent) using user.Lookup(owner) and user.LookupGroup(group).

Error Handling:

Numeric values are not validated against the user database. A file may be chowned to a UID or GID that has no matching entry, which is intentional for namespaced or container scenarios.

State Comparison

State comparison reads ownership from the filesystem as the on-disk numeric UID/GID, reverse-resolved to a name when possible by util.GetFileOwner. Because the manifest may use either form, comparison is delegated to util.UserIDMatches and util.GroupIDMatches, which normalize both sides to numeric IDs before comparing. This keeps a manifest stable regardless of which form was chosen.

Working Directory Support

When a manager has a working directory set (e.g., from extracted manifest), the source property path is adjusted:

func (t *Type) adjustedSource(properties *model.FileResourceProperties) string {
    source := properties.Source
    if properties.Source != "" && t.mgr.WorkingDirectory() != "" {
        source = filepath.Join(t.mgr.WorkingDirectory(), properties.Source)
    }
    return source
}

This allows manifests to use relative paths for source files bundled with the manifest.

Platform Support

The Posix provider uses Unix-specific system calls:

The provider has separate implementations for Unix and Windows (file_unix.go, file_windows.go in internal/util), with Windows returning errors for ownership operations.

Security Considerations

Atomic Writes

Files are written atomically via temp file + rename. This prevents:

• Partial file reads during write
• Corruption if process is interrupted
• Race conditions with concurrent readers

Permission Ordering

Permissions and ownership are set on the temp file before rename:

1. Chmod - Set permissions
2. Write content
3. Chown - Set ownership
4. Rename to target

This ensures the file never exists at the target path with incorrect permissions.

Path Validation

File paths must be absolute and clean (no . or .. components):

if filepath.Clean(p.Name) != p.Name {
    return fmt.Errorf("file path must be absolute")
}

Required Properties

Owner, group, and mode are required properties and cannot be empty, preventing accidental creation of files with default/inherited permissions.

APT Provider

This document describes the implementation details of the APT package provider for Debian-based systems.

Environment

All commands are executed with the following environment variables to ensure non-interactive operation:

Concurrency

A global package lock (model.PackageGlobalLock) is held during all command executions to prevent concurrent apt/dpkg operations within the same process. This prevents lock contention on /var/lib/dpkg/lock.

Operations

Status Check

Command:

dpkg-query -W -f='${Package} ${Version} ${Architecture} ${db:Status-Status}' <package>

Behavior:

• Exit code 0 with installed status → Package is present, returns version info
• Exit code non-zero OR status not installed → Package is absent

Package States: The db:Status-Status field can return various values. Only installed is treated as present:

Treating non-installed states as absent allows apt-get install to repair broken installations.

Install

Ensure Present:

apt-get install -y -q -o DPkg::Options::=--force-confold <package>

Ensure Latest:

apt-cache policy <package>                    # Get candidate version
apt-get install -y -q -o DPkg::Options::=--force-confold <package>=<version>

Specific Version:

apt-get install -y -q -o DPkg::Options::=--force-confold --allow-downgrades <package>=<version>

Flags:

Upgrade

Delegates to Install() with the target version. The --allow-downgrades flag is only added for specific version requests, not for latest.

Downgrade

Delegates to Install() with the target version. The --allow-downgrades flag enables this operation.

Uninstall

Command:

apt-get -q -y remove <package>

Note: Uses remove not purge, so configuration files are preserved. A subsequent install will find existing config files.

Latest Available Version

Command:

apt-cache policy <package>

Parsing: Extracts the Candidate: line from output.

Example output:

zsh:
  Installed: 5.9-8+b18
  Candidate: 5.9-8+b18
  Version table:
 *** 5.9-8+b18 500
        500 http://deb.debian.org/debian trixie/main amd64 Packages
        100 /var/lib/dpkg/status

Version Comparison

Version comparison follows the Debian Policy Manual algorithm.

Version Format

[epoch:]upstream_version[-debian_revision]

Examples:

• 1.0 → epoch=0, upstream=1.0, revision=""
• 1:2.0-3 → epoch=1, upstream=2.0, revision=3
• 2:1.0.0+git-20190109-0ubuntu2 → epoch=2, upstream=1.0.0+git-20190109, revision=0ubuntu2

Comparison Algorithm

1. Compare epochs numerically - Higher epoch wins regardless of other components

2. Compare upstream_version and debian_revision using the Debian string comparison:

   The string is processed left-to-right in segments:

   a. Tildes (~) - Compared first. More tildes = earlier version. Tilde sorts before everything, even empty string.

   • 1.0~alpha < 1.0 (tilde before empty)
   • 1.0~~ < 1.0~ (more tildes = earlier)

   b. Letters (A-Za-z) - Compared lexically (ASCII order)

   • Letters sort before non-letters

   c. Non-letters (., +, -) - Compared lexically

   d. Digits - Compared numerically (not lexically)

   • 9 < 13 (numeric comparison)

   These steps repeat until a difference is found or both strings are exhausted.

Comparison Examples

Implementation

The version comparison is implemented in version.go, ported from Puppet’s Puppet::Util::Package::Version::Debian module. It provides:

• ParseVersion(string) - Parse a version string into components
• CompareVersionStrings(a, b) - Compare two version strings directly
• Version.Compare(other) - Compare parsed versions (-1, 0, 1)
• Helper methods: LessThan, GreaterThan, Equal, etc.

DNF Provider

This document describes the implementation details of the DNF package provider for RHEL/Fedora-based systems.

Concurrency

A global package lock (model.PackageGlobalLock) is held during all command executions to prevent concurrent dnf/rpm operations within the same process. This prevents lock contention on the RPM database.

Operations

Status Check

Command:

rpm -q <package> --queryformat '%{NAME} %|EPOCH?{%{EPOCH}}:{0}| %{VERSION} %{RELEASE} %{ARCH}'

Query Format (NEVRA): The query format extracts the full NEVRA (Name, Epoch, Version, Release, Architecture):

Example output:

zsh 0 5.8 9.el9 x86_64

Behavior:

• Exit code 0 → Package is present, parses NEVRA components
• Exit code non-zero → Package is absent

Returned Version Format: The version returned combines VERSION and RELEASE: 5.8-9.el9

The epoch and release are stored separately in the Extended metadata.

Install

Ensure Present or Latest:

dnf install -y <package>

Specific Version:

dnf install -y <package>-<version>

Flags:

Note: DNF uses - (hyphen) to separate package name from version, unlike APT which uses =.

Upgrade

Delegates to Install(). DNF’s install command handles upgrades automatically when a newer version is available or specified.

Downgrade

Command:

dnf downgrade -y <package>-<version>

Note: Unlike upgrade, downgrade uses a dedicated DNF command rather than delegating to install.

Uninstall

Command:

dnf remove -y <package>

Version Format

RPM versions follow the EVR (Epoch:Version-Release) format:

[epoch:]version-release

Examples:

• 5.8-9.el9 → epoch=0, version=5.8, release=9.el9
• 1:2.0-3.fc39 → epoch=1, version=2.0, release=3.fc39
• 0:1.0.0-1.el9 → epoch=0 (explicit), version=1.0.0, release=1.el9

Version Comparison

Version comparison uses a generic algorithm ported from Puppet, implemented in internal/util.VersionCmp().

Algorithm

The version string is tokenized into segments by splitting on -, ., digits, and non-digit sequences. Segments are compared left-to-right:

1. Hyphens (-) - A hyphen loses to any other character
2. Dots (.) - A dot loses to any non-hyphen character
3. Digit sequences - Compared numerically, except:
   • Leading zeros trigger lexical comparison (01 vs 1 compared as strings)
4. Non-digit sequences - Compared lexically (case-insensitive)

If all segments match, falls back to whole-string comparison.

Trailing Zero Normalization

When ignoreTrailingZeroes is enabled, trailing .0 segments before the first - are removed:

• 1.0.0-rc1 → 1-rc1
• 2.0.0 → 2

This allows 1.0.0 to equal 1.0 when the flag is set.

Comparison Examples

Implementation

The version comparison is implemented in internal/util/util.go and provides:

• VersionCmp(a, b, ignoreTrailingZeroes) - Compare two version strings
• Returns -1 (a < b), 0 (a == b), or 1 (a > b)

Choria Provider

This document describes the implementation details of the Choria scaffold provider for rendering template directories using the choria-io/scaffold library.

Provider Selection

The Choria provider is the default and only scaffold provider. It is always available and returns priority 1 for all scaffold resources.

Operations

Scaffold (Render Templates)

Process:

1. Check if target directory exists
2. Configure scaffold with source, target, engine, delimiters, post-processing, and skip_empty settings
3. Create scaffold instance using the appropriate engine (scaffold.New() for Go, scaffold.NewJet() for Jet)
4. Call Render() (real mode) or RenderNoop() (noop mode)
5. Categorize results into changed, stable, and purged file lists

Scaffold Configuration:

Engine Selection:

Result Categorization:

File paths in the metadata lists are absolute paths, constructed by joining the target directory with the relative path from the scaffold result.

Purge Behavior:

When purge is enabled and a file has FileActionRemove, the provider deletes the file from disk during Scaffold(). In noop mode, the removal is logged but not performed. When purge is disabled, purged files are only tracked in metadata and not removed.

Status

Process:

1. Perform a dry-run render (noop mode) to determine what the scaffold would do
2. When ensure is absent, filter Changed and Stable lists to only include files that actually exist on disk

The noop render reports what would happen if the scaffold were applied. For ensure: present, this is the desired output — it shows what needs to change. For ensure: absent, the raw render output is misleading after removal (it would show files to be added), so the lists are filtered to reflect what managed files actually remain on disk.

State Detection:

Remove

Process:

1. Collect managed files from the state’s Changed and Stable lists (purged files are not removed as they don’t belong to the scaffold)
2. Remove each file individually
3. Track parent directories of removed files
4. Iteratively remove empty directories deepest-first
5. Stop when no more empty directories can be removed
6. Best-effort removal of the target directory (only succeeds if empty)

File Removal Order:

Files are collected from two metadata lists:

1. Changed - Files that were added or modified
2. Stable - Files that were unchanged

Purged files are not removed because they are unrelated to the scaffold and may belong to other processes.

Directory Cleanup:

For each removed file:
    Track its parent directory

Repeat:
    For each tracked directory:
        Skip if it is the target directory itself
        Skip if not empty
        Remove the directory
        Track its parent directory
Until no more directories removed

Best-effort: remove the target directory (fails silently if not empty)

The target directory is removed if empty after all managed files and subdirectories are cleaned up. If unrelated files remain (purged files), the directory is preserved.

Error Handling:

Template Environment

Templates receive the full templates.Env environment, which provides access to:

• facts - System facts for the managed node
• data - Hiera-resolved configuration data, or custom data when the resource’s data property is set
• Template helper functions

When the scaffold resource has a data property set, env.Data is replaced with the custom data before the provider’s Status() and Scaffold() methods are called. The provider receives the already-resolved environment and does not need to handle this override itself.

This allows templates to generate host-specific configurations based on facts and hierarchical data.

Logging

The provider wraps the CCM logger in a scaffold-compatible interface:

type logger struct {
    log model.Logger
}

func (l *logger) Debugf(format string, v ...any)
func (l *logger) Infof(format string, v ...any)

This adapter translates the scaffold library’s Debugf/Infof calls to CCM’s structured logging.

Platform Support

The Choria provider is platform-independent. It uses the choria-io/scaffold library for template rendering, which operates on standard filesystem operations. No platform-specific system calls are used.

Systemd Provider

This document describes the implementation details of the Systemd service provider for managing system services via systemctl.

Provider Selection

The Systemd provider is selected when systemctl is found in the system PATH. The provider checks for the executable using util.ExecutableInPath("systemctl").

Availability Check:

• Searches PATH for systemctl
• Returns priority 1 if found
• Returns unavailable if not found

Concurrency

A global service lock (model.ServiceGlobalLock) is held during all systemctl command executions to prevent concurrent systemd operations within the same process. This prevents race conditions when multiple service resources are managed simultaneously.

func (p *Provider) execute(ctx context.Context, cmd string, args ...string) (...) {
    model.ServiceGlobalLock.Lock()
    defer model.ServiceGlobalLock.Unlock()
    return p.runner.Execute(ctx, cmd, args...)
}