File Type

This document describes the design of the file resource type for managing files and directories.

Overview

The file resource manages files and directories with three aspects:

Existence: Whether the file/directory exists or is absent
Content: The contents of a file (from inline content or source file)
Attributes: Owner, group, and permissions

Provider Interface

File providers must implement the FileProvider interface:

type FileProvider interface {
    model.Provider

    CreateDirectory(ctx context.Context, dir string, owner string, group string, mode string) error
    Store(ctx context.Context, file string, contents []byte, source string, owner string, group string, mode string) error
    SetAttributes(ctx context.Context, file string, owner string, group string, mode string) error
    Remove(ctx context.Context, file string, force bool) error
    Status(ctx context.Context, file string) (*model.FileState, error)
}

Method Responsibilities

Method	Responsibility
`Status`	Query current file state (existence, type, content hash, attributes)
`Store`	Create or update a file with content and attributes
`SetAttributes`	Update owner, group and mode on an existing file without changing its content
`CreateDirectory`	Create a directory with attributes
`Remove`	Remove a file or directory; honors `force` for non-empty directories

Status Response

The Status method returns a FileState containing:

type FileState struct {
    CommonResourceState
    Metadata *FileMetadata
}

type FileMetadata struct {
    Name     string         // File path
    Checksum string         // SHA256 hash of contents (files only)
    Owner    string         // Owner username
    Group    string         // Group name
    Mode     string         // Permissions in octal (e.g., "0644")
    Provider string         // Provider name (e.g., "posix")
    MTime    time.Time      // Modification time
    Size     int64          // File size in bytes
    Extended map[string]any // Provider-specific metadata
}

The Ensure field in CommonResourceState is set to:

present if a regular file exists
directory if a directory exists
absent if the path does not exist

Available Providers

Provider	Platform	Documentation
`posix`	Unix/Linux	Posix

Ensure States

Value	Description
`present`	Path must be a regular file with specified content
`absent`	Path must not exist (see Removal Behavior)
`directory`	Path must be a directory

Content Sources

Files can receive content from two mutually exclusive sources:

Property	Description
`contents`	Inline string content (template-resolved)
`source`	Path to local file to copy from

# Inline content with template
- file:
    - /etc/motd:
        ensure: present
        content: |
          Welcome to {{ lookup('facts.hostname') }}
          Managed by CCM
        owner: root
        group: root
        mode: "0644"

# Copy from source file
- file:
    - /etc/app/config.yaml:
        ensure: present
        source: files/config.yaml
        owner: app
        group: app
        mode: "0640"

When using source, the path is relative to the manifest’s working directory if one is set.

Attribute-only Management

A file resource that omits both content and source manages only owner, group and mode. The file’s contents are left untouched. This is useful when another resource (typically an exec or package) produces the file and CCM is responsible for enforcing its permissions.

- file:
    - /etc/sysconfig/myapp:
        ensure: present
        owner: root
        group: root
        mode: "0640"

Rules:

If the file exists, only owner, group and mode are adjusted. Content is never read or written.
If the file does not exist, an empty file is created with the requested owner, group and mode. This matches the behavior of Puppet’s file { ensure => present } with no content or source.
If the path exists as a directory, the apply fails. Use ensure: directory to manage directories.
Symlinks are rejected by the posix provider’s SetAttributes implementation to avoid silently mutating the target through the link.

To create an explicit empty file rather than enter attribute-only mode, set content: "". An omitted content: and content: null are equivalent and both mean “do not manage content”.

content and source remain mutually exclusive. Setting both is rejected at validation time.

Required Properties

Unlike some resources, file resources require explicit attributes:

Property	Required	Description
`owner`	Yes, except absent	Username or numeric UID that owns the file
`group`	Yes, except absent	Group name or numeric GID that owns the file
`mode`	Yes, except absent	Permissions in octal notation

This prevents accidental creation of files with default or inherited permissions.

When ensure: absent, owner, group, and mode are optional. They describe a desired on-disk state and are not consulted during removal. Manifests that only ever remove a path may omit them.

- file:
    - /tmp/leftover.lock:
        ensure: absent

A purely-numeric value for owner or group is always interpreted as a UID or GID respectively, without consulting /etc/passwd or /etc/group. This matches the semantics of chown(1) for numeric arguments and allows the resource to be applied on systems where the target account exists only by ID (containers, mounted volumes from other hosts, namespaced filesystems).

Removal Behavior

The force property controls how ensure: absent handles directories.

Property	Default	Description
`force`	`false`	When `true`, allow `ensure: absent` to remove non-empty directories

- file:
    - /var/lib/myapp:
        ensure: absent
        force: true
        owner: root
        group: root
        mode: "0755"

Rules:

force is only valid when ensure: absent. Combining it with any other ensure value is rejected at validation time.
force: true cannot be used with name: /. All other paths are allowed; CCM does not maintain a blocklist of system directories.
For regular files and symlinks, force has no effect; both forms call into the same removal path.
If a directory is a symlink, only the symlink itself is removed. The target directory is left untouched. See the posix provider for details.
Without force, attempting to remove a non-empty directory fails with a hint that force: true is required. Once force is removed from the manifest, future applies will fail again if the directory is repopulated. That is intentional: the manifest must opt in to destructive behavior every time it is applied.

Apply Logic

┌─────────────────────────────────────────┐
│ Get current state via Status()          │
└─────────────────┬───────────────────────┘
                  │
                  ▼
┌─────────────────────────────────────────┐
│ Is current state desired state?         │
└─────────────────┬───────────────────────┘
              Yes │         No
                  ▼         │
          ┌───────────┐     │
          │ No change │     │
          └───────────┘     │
                            ▼
              ┌─────────────────────────┐
              │ What is desired ensure? │
              └─────────────┬───────────┘
                            │
    ┌───────────────────────┼───────────────────────┐
    │ absent                │ directory             │ present
    ▼                       ▼                       ▼
┌────────────┐      ┌───────────────┐      ┌───────────────────────────────┐
│ Remove     │      │ CreateDir     │      │ Content managed or file       │
│ (provider) │      │               │      │ absent? Store. Otherwise      │
└────────────┘      └───────────────┘      │ SetAttributes.                │
                                           └───────────────────────────────┘

Idempotency

The file resource checks multiple attributes for idempotency:

State Checks (in order)

Ensure match: Current type matches desired (present/absent/directory)
Content match: SHA256 checksum of contents matches (for ensure: present, skipped in attribute-only mode)
Owner match: Current owner matches desired, comparing by numeric UID when either side is a numeric value or resolves to one
Group match: Current group matches desired, comparing by numeric GID when either side is a numeric value or resolves to one
Mode match: Current permissions match desired

Decision Table

Desired	Current State	Action
`absent`	absent	None
`absent`	present (file or symlink)	Remove
`absent`	empty directory	Remove
`absent`	non-empty directory + `force: false`	Error: directory is not empty
`absent`	non-empty directory + `force: true`	Remove recursively
`directory`	directory + matching attrs	None
`directory`	absent/present	CreateDirectory
`directory`	directory + wrong attrs	CreateDirectory (updates attrs)
`present` (content set)	present + matching all	None
`present` (content set)	absent	Store
`present` (content set)	present + wrong content	Store
`present` (content set)	present + wrong attrs	Store
`present` (attrs-only)	present + matching attrs	None
`present` (attrs-only)	present + wrong attrs	SetAttributes
`present` (attrs-only)	absent	Store (creates empty file with attrs)
`present` (any mode)	directory	Error: path exists as a directory

Content Comparison

Content is compared using SHA256 checksums:

Source	Checksum Method
`contents` property	`Sha256HashBytes([]byte(contents))`
`source` property	`Sha256HashFile(adjustedPath)`
Existing file	`Sha256HashFile(filePath)`

Mode Validation

File modes are validated during resource creation:

Valid Formats:

"0644" - Standard octal
"644" - Without leading zero
"0o755" - With 0o prefix
"0O700" - With 0O prefix

Validation Rules:

Must be valid octal number (digits 0-7)
Must be ≤ 0777 (no setuid/setgid/sticky via mode)

Path Validation

File paths must be:

Absolute (start with /)
Clean (no . or .. components, filepath.Clean(path) == path)

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

Working Directory

When a manifest has a working directory (e.g., extracted from an archive), the source property is resolved relative to it:

if properties.Source != "" && mgr.WorkingDirectory() != "" {
    source = filepath.Join(mgr.WorkingDirectory(), properties.Source)
}

This allows manifests bundled with their source files to use relative paths.

Noop Mode

In noop mode, the file type:

Queries current state normally
Computes content checksums
Logs what actions would be taken
Sets appropriate NoopMessage:
- “Would have created the file”
- “Would have created an empty file with requested attributes” (attribute-only mode, file absent)
- “Would have updated attributes” (attribute-only mode, attribute drift)
- “Would have created directory”
- “Would have removed the file” (regular file or symlink)
- “Would have removed the directory” (directory, force not set)
- “Would have recursively removed the directory” (directory, force: true)
Reports Changed: true if changes would occur
Does not call provider Store/CreateDirectory methods
Does not remove files

Desired State Validation

After applying changes (in non-noop mode), the type verifies the file reached the desired state by calling Status() again and checking all attributes match. If validation fails, ErrDesiredStateFailed is returned.

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:

Verify parent directory exists
Parse file mode from octal string
Open source file if source property is set
Create temporary file in the same directory as target
Set file permissions on temp file
Write content (from source file or contents property)
Set ownership (chown) on temp file
Close temp file
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:

Property	Behavior
`contents`	Write string directly to file (template-resolved)
`source`	Copy from local file path (adjusted for working directory)

If both are empty, an empty file is created.

Error Handling:

Condition	Behavior
Parent directory doesn’t exist	Return error: “is not a directory”
Invalid mode format	Return error from `strconv.ParseUint`
Source file not found	Return error from `os.Open`
Permission denied	Return error from underlying syscall
Rename failure	Return error: “could not rename temporary file”

CreateDirectory

Process:

Parse file mode from octal string
Create directory and parents via os.MkdirAll()
Lookup numeric UID/GID from owner/group names
Set permissions via os.Chmod() (ensures correct mode even if umask affected MkdirAll)
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:

Condition	Behavior
Path does not exist	Return `nil`
`force: false`, directory not empty	Return wrapped error: `"cannot remove <path>: directory is not empty, set 'force: true' ..."`
Other syscall failure	Return error from underlying syscall

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:

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

State Detection:

`os.Stat()` Result	Ensure Value	Metadata
File exists	`present`	Size, mtime, owner, group, mode, checksum
Directory exists	`directory`	Size, mtime, owner, group, mode
`os.ErrNotExist`	`absent`	None
`os.ErrPermission`	`absent`	None (logged as warning)
Other error	(unchanged)	None (logged as warning)

Metadata Collection:

Field	Source
`Name`	From properties
`Provider`	“posix”
`Size`	`FileInfo.Size()`
`MTime`	`FileInfo.ModTime()`
`Owner`	`util.GetFileOwner()` - resolves UID to username
`Group`	`util.GetFileOwner()` - resolves GID to group name
`Mode`	`util.GetFileOwner()` - octal string (e.g., “0644”)
`Checksum`	`util.Sha256HashFile()` - SHA256 hash (files only)

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

Ensure value matches - present, absent, or directory
Content checksum matches - SHA256 of contents vs existing file (for files only)
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
Group matches - Group comparison, normalized through util.GroupIDMatches using the same rules
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:

Content Source	Checksum Calculation
`contents` property	`Sha256HashBytes([]byte(contents))`
`source` property	`Sha256HashFile(adjustedSourcePath)`

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

Mode Validation

File modes are validated during resource creation:

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

Valid Mode Examples:

Input	Parsed Value
`"0644"`	0o644
`"644"`	0o644
`"0o755"`	0o755
`"0O700"`	0o700

Invalid Mode Examples:

Input	Error
`"0888"`	Invalid octal digit
`"1777"`	Exceeds maximum (setuid/setgid not supported via mode)
`"rw-r--r--"`	Not octal format

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:

Condition	Behavior
Empty value	Return error: “user name cannot be empty” or “group name cannot be empty”
Named user not in database	Return error: “could not lookup user”
Named group not in database	Return error: “could not lookup group”
Numeric value out of int range	Return error from `strconv.Atoi`

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:

Operation	System Call
Get file owner/group	`syscall.Stat_t` (UID/GID from stat)
Set ownership	`os.Chown()` → `chown(2)`
Set permissions	`os.Chmod()` → `chmod(2)`

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:

Chmod - Set permissions
Write content
Chown - Set ownership
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.

File Type

Overview

Provider Interface

Method Responsibilities

Status Response

Available Providers

Ensure States

Content Sources

Attribute-only Management

Required Properties

Removal Behavior

Apply Logic

Idempotency

State Checks (in order)

Decision Table

Content Comparison

Mode Validation

Path Validation

Working Directory

Noop Mode

Desired State Validation

Subsections of File Type

Posix Provider

Provider Selection

Operations

Store (Create/Update File)

CreateDirectory

Remove

Status

Idempotency

State Checks

Decision Flow

Content Comparison

Mode Validation

Ownership Resolution

State Comparison

Working Directory Support

Platform Support

Security Considerations

Atomic Writes

Permission Ordering

Path Validation

Required Properties