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.

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 - Username comparison
4. Group matches - Group name comparison
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 names are resolved to numeric UID/GID via:

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

This uses the system’s user database (/etc/passwd, /etc/group, or equivalent):

• user.Lookup(owner) → UID
• user.LookupGroup(group) → GID

Error Handling:

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.