windows_ad_domain_controller

Experimental. This Windows host as another domain controller, and DNS server, in an Active Directory domain that exists. It never reboots: reboot_required says Windows wants one, and windows_reboot does it. Removing the step leaves the domain controller; nothing is demoted.

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

Use windows_ad_domain_controller to add a domain controller to a domain that already exists. Two DCs mean the domain keeps answering when one is down. It never reboots the host, and promotion always needs a reboot, so follow it with a windows_reboot step, then wait for AD to answer.

Example usage

The host needs the AD DS role, and DNS that finds the domain.

step "ad_ds" {
  windows_feature {
    name                     = "AD-Domain-Services"
    include_management_tools = true
  }
}

step "dc" {
  windows_ad_domain_controller {
    domain_name           = "lab.example.com"
    username              = "LAB\\azadmin"
    password_wo           = "use an ephemeral variable here"
    safe_mode_password_wo = "use an ephemeral variable here"
  }
}

step "promoted" {
  windows_reboot {
    only_if_pending = true
    timeout         = "15m"
  }
}

step "adws" {
  windows_wait_for {
    port    = 9389
    timeout = "10m"
  }
}

Arguments

Name	Type	Required	Description
database_path	string	No	Folder for the AD database. Windows’ default is C:\Windows\NTDS. Used only when promoting.
domain_name	string	Yes	DNS name of the domain, such as lab.example.com.
log_path	string	No	Folder for the AD logs. Used only when promoting.
password_wo	string	No	Password for username, kept out of plan and state. Needed to promote, and used only then.
safe_mode_password_wo	string	No	Directory Services Restore Mode password for this domain controller, kept out of plan and state. Needed to promote, and used only then: changing it later changes nothing on the host.
sysvol_path	string	No	Folder for SYSVOL. Used only when promoting.
timeout	string	No	How long promotion may take. Defaults to “30m”.
username	string	Yes	Domain account that may add domain controllers, such as LAB\admin, a member of Domain Admins. Used only when promoting.

Read-only attributes

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

Name	Type	Description
in_sync	bool	Whether the host was a domain controller in this domain at the last refresh.
reboot_required	bool	Whether Windows reported wanting a reboot after the last change. Promotion always does.
revision	string	Changes each time Conn3x changes this on the host. Handlers watch it.

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

How it works

Promotion. Conn3x runs Install-ADDSDomainController with -InstallDns and -NoRebootOnCompletion, so the new DC is a DNS server and a global catalog, as Windows makes one by default. Join the host to the domain first with windows_domain_membership: that’s the path Conn3x has been tested on. On a 2-vCPU VM promotion takes about a minute.

Why it needs a password. A key login has no password to show the domain, so promotion uses the account in username and password_wo. It has to be able to add domain controllers: a member of Domain Admins can.

The passwords. password_wo and safe_mode_password_wo go to the host on stdin and become SecureString values through .NET before the cmdlet sees them, so a logging policy that records cmdlet parameters records only the type name. They’re never in plan or state, and they’re blanked from errors. Both are used once, at promotion. To change the Directory Services Restore Mode password later, use ntdsutil on the host.

Reboots. reboot_required is true after promotion, and promotion leaves the marker windows_reboot with only_if_pending looks for. sshd answers before AD does, which is why the example waits for Active Directory Web Services on port 9389.

Reads change nothing. A refresh reads the host’s domain role, its domain and NTDS’s root domain from the registry, and loads no AD tools. A host promoted but not yet rebooted counts as a DC while the reboot marker is there.

Folders. database_path, log_path and sysvol_path are checked as windows_ad_forest checks them: a folder that exists must be empty, owned by an administrator, not a link, and writable by nobody else. A missing one is made with SYSTEM and Administrators only.

Settings used once. username and the folders apply only at promotion. Changing domain_name plans a new promotion, which fails: Conn3x won’t demote the host.

Logging in afterwards. A domain controller has no local accounts. Seen on Azure, the bare name, such as azadmin, logs in as the domain’s account of that name after promotion, with the domain’s password for it and the same key. A local login, such as win2\azadmin or .\azadmin, stops working, so Conn3x refuses to promote with one.

What it refuses. A host that’s a domain controller already, in any domain, and a host that’s a member of another domain.

Removal

Deleting a windows_ad_domain_controller step leaves the domain controller as it is. Conn3x never demotes one. Delete the VM, or run Uninstall-ADDSDomainController yourself.