windows_acl

Experimental. Access rules on a file or folder that already exists on a Windows host. Rules are compared by SID, so names and case cause no difference. It won’t follow a link. Removing the step leaves the rules as they are.

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

Use windows_acl for access rules on a file or folder that already exists on a Windows host. By default it only adds what’s listed. Rules are compared by SID, so a name in another case or another display language never shows as a change.

Example usage

Add a rule:

step "uploads" {
  windows_acl {
    path = "C:\\app\\uploads"

    entry {
      principal = "BUILTIN\\IIS_IUSRS"
      rights    = ["Modify"]
    }
  }
}

Make the list the whole truth, with nothing inherited:

step "lock_down" {
  windows_acl {
    path          = "C:\\app\\private"
    authoritative = true
    inherit       = false
    owner         = "S-1-5-32-544"

    entry {
      principal = "S-1-5-32-544"
      rights    = ["FullControl"]
    }
    entry {
      principal = "S-1-5-18"
      rights    = ["FullControl"]
    }
    entry {
      principal = "S-1-1-0"
      rights    = ["Write"]
      type      = "deny"
    }
  }
}

Arguments

Name	Type	Required	Description
authoritative	bool	No	Remove any rule set directly on the path that isn’t listed here. Defaults to false, which only adds. Rules it inherits stay; set inherit = false to drop those.
inherit	bool	No	Whether the path inherits rules from its folder. Left as it is when unset.
owner	string	No	Owning user or group. Left as it is when unset.
path	string	Yes	Full path on a local drive.

Read-only attributes

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

Name	Type	Description
in_sync	bool	Whether the rules matched at the last refresh.
revision	string	Changes each time Conn3x changes this on the host. Handlers watch it.

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

How it works

Links. It won’t change rules through a symbolic link, junction or mount point, at the path or on the way to it, and refuses a file with other hard links, since rules belong to the file and not the name. Rules on a folder reach what’s inside it, but stop at a link inside it.

Folders others can change. It holds every folder on the way open while it works, and refuses one that another account could change. See windows_file for exactly what counts.

Inherited rules. authoritative removes rules set directly on the path. Rules it inherits stay until inherit = false.

A missing principal is an error at apply. A refresh shows it as a difference.

Removal

Deleting a windows_acl step leaves the rules as they are.