windows_file

Experimental. A file on a Windows host, written byte for byte: no line ending conversion. It never writes through a link, and refuses a folder on the way that another account could change.

Experimental. Windows support is new, and this module may change between releases.

Use windows_file to put a file on a Windows host, byte for byte. Line endings stay as you wrote them, and the file appears all at once, so nothing ever reads half of it.

Example usage

step "config" {
  windows_file {
    path    = "C:\\app\\config.json"
    content = jsonencode({ port = 8080 })
  }
}

A secret stays out of the plan and state. Only SYSTEM and Administrators can read the file, from the moment it exists:

step "api_key" {
  windows_file {
    path       = "C:\\app\\api.key"
    content_wo = "use an ephemeral variable here"
  }
}

Name who gets access yourself:

step "readable_by_the_app" {
  windows_file {
    path    = "C:\\app\\settings.ini"
    content = "mode = production\n"

    acl {
      principal = "S-1-5-32-544"
      rights    = ["FullControl"]
    }
    acl {
      principal = "S-1-5-18"
      rights    = ["FullControl"]
    }
    acl {
      principal = "NT SERVICE\\MyApp"
      rights    = ["Read"]
    }
  }
}

Arguments

Name	Type	Required	Description
content	string	One of	Exact content, up to 2 MiB. Set this or content_wo.
content_wo	string	One of	Exact content, kept out of state: state records only content_hmac. Use it for secrets. Unless acl is set, only SYSTEM and Administrators can read the file.
on_remove	string	No	What happens on the host when this resource is removed: “forget” (default) leaves the file, “delete” removes it.
path	string	Yes	Full path on a local drive, such as C:\app\config.json. Its folder must already exist.

Read-only attributes

Conn3x sets these; reference them as conn3x_windows_file.<circuit>__<step>["<host>"].<name>.

Name	Type	Description
content_hmac	string	HMAC-SHA256 over the path and the SHA-256 of content_wo, keyed by CONN3X_HMAC_KEY or ~/.config/conn3x/hmac.key. Null when content is used.
in_sync	bool	Whether the file’s rules matched at the last refresh.
revision	string	Changes each time Conn3x changes this on the host. Handlers watch it.
sha256	string	SHA-256 of the file, hex encoded. Null with content_wo.

A step lowers to the conn3x_windows_file resource, one instance per host, and connects with its circuit’s ssh block.

How it works

Writing. Conn3x makes a temp file beside the target with its access rules already on it, writes the content, then renames it over the target in one step. A target that’s already there with looser rules can’t expose a new secret.

Links. It never writes through a symbolic link, a junction or a mount point, at the path or on the way to it, and it refuses a file with other hard links. Use the real path.

Folders others can change. While it writes, every folder on the way is held open, so none can be renamed or removed. With content_wo or acl it also refuses a folder that belongs to, or lets delete from, rename or re-permission, anyone but SYSTEM, Administrators, TrustedInstaller or the login itself, since that account could replace the file afterwards. The right to add new entries is fine. On a stock Azure image, every signed-in user can modify a new folder under C:\, so give that folder its own rules with windows_directory’s acl before putting a secret below it.

The folder must already exist. Make it with windows_directory first.

Rules on an existing file. With no acl and no content_wo, a rewrite keeps the rules already on the file, unless another account owns it. Use acl, or windows_acl for a few added rules, but not both on one path.

Secrets. content_wo travels on stdin. Refresh compares a keyed hash of the file’s SHA-256 with state, so drift still shows and the content never leaves the host again. Errors have the value blanked.

Size. Content is limited to 2 MiB.

Removal

By default, deleting a windows_file step leaves the file. With on_remove = "delete" it deletes the file, or a link standing in its place, but never what a link points to.