windows_ad_ou

Experimental. An organizational unit in Active Directory, run on a domain controller. Settings left unset are left as they are.

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

Use windows_ad_ou to keep an organizational unit in Active Directory. Run it on a domain controller: that’s where your SSH login is a domain account.

Example usage

step "lab_ou" {
  windows_ad_ou {
    name        = "Lab"
    description = "Made by Conn3x"
  }
}

An OU inside another one names its parent in path:

step "servers_ou" {
  windows_ad_ou {
    name = "Servers"
    path = "OU=Lab,DC=lab,DC=example,DC=com"
  }
}

Arguments

Name	Type	Required	Description
description	string	No	Description.
name	string	Yes	OU name, such as Servers.
on_remove	string	No	What happens in the domain when this resource is removed: “forget” (default) leaves the OU; it never deletes one that’s protected or not empty, “delete” deletes it.
path	string	No	Distinguished name of the parent, such as OU=Lab,DC=lab,DC=example,DC=com. Unset is the top of the domain. Changing it makes a new OU.
protected	bool	No	Whether the OU is protected from accidental deletion. Unset, a new OU is protected, as Windows does.

Read-only attributes

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

Name	Type	Description
in_sync	bool	Whether the OU 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_ad_ou resource, one instance per host, and connects with its circuit’s ssh block.

How it works

Where it runs. On a domain controller, after the reboot that finishes its promotion, so follow windows_ad_forest with a reboot. On a member server with the AD tools installed it would still fail, because a key login there has no domain credentials to reach AD with.

Waiting for AD. Straight after a DC reboots, Active Directory can answer for the domain a minute before its global catalog does, and a write made in that minute can hang. So apply first waits until a query through the global catalog works too, for up to 10 minutes, then fails with the reason AD last gave. A write that gets no answer at all runs once more when AD answers again. It reads first, so it only writes what’s still missing. A host that isn’t a DC isn’t waited on.

Finding it. The OU is looked up by name directly under path, or under the top of the domain when path is unset. So changing either plans a new OU, and the old one is forgotten, not moved.

Protection. Windows protects a new OU from accidental deletion, and so does Conn3x unless you set protected = false. Leave protected unset to keep whatever the OU has.

Drift. A refresh reads the description and the protection flag. If someone changes either in Active Directory Users and Computers, the next plan shows the step out of sync, and conn3x drift exits 2.

Reads change nothing. A refresh only runs Get-ADObject and Get-ADOrganizationalUnit. A host without the ActiveDirectory module reads as having no OU, rather than failing.

Removal

By default, deleting a windows_ad_ou step leaves the OU and everything in it. With on_remove = "delete" Conn3x deletes it, but only when it’s empty and not protected: it never deletes what’s inside an OU. Set protected = false and apply first, then remove the step.