dnscontrol/providers/activedir/doc.md

ActiveDirectory

This provider updates a DNS Zone in an ActiveDirectory Integrated Zone.

When run on Windows, AD is updated directly. The code generates PowerShell commands, executes them, and checks the results. It leaves behind a log file of the commands that were generated.

When run on non-Windows, AD isn't updated because we can't execute PowerShell at this time. Instead of reading the existing zone data from AD, It learns what records are in the zone by reading adzonedump.{ZONENAME}.json, a file that must be created beforehand. It does not actually update AD, it generates a file with PowerShell commands that would do the updates, which you must execute afterwords. If the adzonedump.{ZONENAME}.json does not exist, the zone is quietly skipped.

Not implemented:

• Delete records. This provider will not delete any records. It will only add and change existing records. See "Note to future devs" below.
• Update TTLs. It ignores TTLs.

required creds.json config

No "creds.json" configuration is expected.

example dns config js:

var REG_NONE = NewRegistrar('none', 'NONE')
var DSP_ACTIVEDIRECTORY_DS = NewDSP("activedir", "ACTIVEDIRECTORY_PS");

D('ds.stackexchange.com', REG_NONE,
    DSP_ACTIVEDIRECTORY_DS,
)


    //records handled by another provider...
);

Special Windows stuff

This provider needs to do 2 things:

• Get a list of zone records:

  • powerShellDump: Runs a PS command that dumps the zone to JSON.
  • readZoneDump: Opens a adzonedump.$DOMAINNAME.json file and reads JSON out of it. If the file does not exist, this is considered an error and processing stops.

• Update records:

  • powerShellExec: Execute PS commands that do the update.
  • powerShellRecord: Record the PS command that can be run later to do the updates. This file is -psout=dns_update_commands.ps1

So what happens when? Well, that's complex. We want both Windows and Linux to be able to use -fakewindows for either debugging or (on Windows) actual use. However only Windows permits -fakewinows=false and actually executes the PS code. Here's which algorithm is used for each case:

• If -fakewindows is used on any system: readZoneDump and powerShellRecord is used.
• On Windows (without -fakewindows): powerShellDump and powerShellExec is used.
• On Linux (wihtout -fakewindows): the provider loads as "NONE" and nothing happens.

Note to future devs

Why doesn't this provider delete records?

Because at this time Stack doesn't fully control AD zones using dnscontrol. It only needs to add/change records.

What should we do when it does need to delete them?

Currently NO_PURGE is a no-op. I would change it to update domain metadata to flag that deletes should be enabled/disabled. Then generate the deletes only if this flag exists. To be paranoid, the func that does the deleting could check this flag to make sure that it really should be deleting something.